Currently we just write comments in the code, no documentation generators. It would be useful for my team, problem is time to integrate. Currently we use D2009 haven't managed to move to XE+ yet. Need to find a handy tool :-) however if XE has xml doc comments, might be another reason to push management to move to XE :-)
Lars Fosdal Dont you find xml docs in XE inconvenient ? There is no option to generate doc skeleton for class or function, like in NetBeans, as far as i know.
DevJet's Documentation Insight Express lends some help, Alexey Petushkov - but I am old school. I use code templates to create doc entries at the same time as I create methods, then fill in the blanks.
I have a copy of Documentation Insight that I won in a contest but honestly I don't find much use for code documentation. I've sometimes used JADD on unfamiliar code to make it easier to digest. With my own code if I can't determine a function's purpose from its name and the names of its parameters I consider it a code smell and refactor it until its blatantly obvious.
Kenneth Cochran You raised some important questions: 1) Why document API? 2) How to document source code? 3) How to generate documentation? For the last two questions, Documentation Insight is definitely a nice tool. For the first question, I think that depends on your situation. If you are API library developer or component developer, Documentation Insight will be your sweet buddy :-)
Baoquan Zuo It is nice to document return values on border conditions and special situations, error handling, exception handling, used pattern for work with class and other questions. Delphi lacks straight and safe strong/week reference management (which problem have been solved in most other languages), so it is important to declare which object owning pattern is used. Today i have lost 5 minutes on invalid pointer crash with x:=TXMLDocument.Create(); x.SaveToFile('yyy'); FreeAndNil(x) "invalid pointer operation" crash :). It is too sad when class MUST be casted to interface to work :)
Baoquan Zuo Yes, I can see documentation being useful for someone developing a public API. I still feel the best documentation is expressive code. Supplementary documentation can easily get out of sync with the code if a team isn't disciplined enough to update it. This is true no matter how easy and convenient the tool you use to maintain it is. I reserve code comments and external documentation for situations where the code simply can't express my intent to my satisfaction.
Kenneth Cochran Yes, I understand your situation. I think an expressive code/design is a MUST and a well-explained documentation when necessary is a nice addition, no matter where they are and what they are. :-)
Kenneth Cochran While expressive code makes it easier to understand "what" is happening, it doesn't always explain "why" it is being done. This is where source code documentation can really help.
In the context of a complete system/application, knowing "why" the code is doing "what" it does can be very helpful to a developer, especially if they're not the original author of the code.
I do agree that keeping documentation up-to-date can be difficult and requires discipline, but this is true of all documentation, not just what may be found in source code.
None :-( I would also like to know what the majority find the most useful.
ReplyDeleteSean Bertinotti Why? It is not useful for you, or there is no handy tool for that ?
ReplyDeleteAfter xml doc comments became available in XE, none.
ReplyDeleteCurrently we just write comments in the code, no documentation generators. It would be useful for my team, problem is time to integrate. Currently we use D2009 haven't managed to move to XE+ yet. Need to find a handy tool :-) however if XE has xml doc comments, might be another reason to push management to move to XE :-)
ReplyDeleteLars Fosdal Dont you find xml docs in XE inconvenient ? There is no option to generate doc skeleton for class or function, like in NetBeans, as far as i know.
ReplyDeleteDevJet's Documentation Insight Express lends some help, Alexey Petushkov - but I am old school. I use code templates to create doc entries at the same time as I create methods, then fill in the blanks.
ReplyDeleteLars Fosdal It is really "must have" tool, thanks
ReplyDeleteDevJet's Documentation Insight V2.7.11.12
ReplyDeleteDocumentation Insight is an up-to-date source code documentation solution in Delphi. Check out: http://www.devjetsoftware.com/products/documentation-insight/
ReplyDeleteI have a copy of Documentation Insight that I won in a contest but honestly I don't find much use for code documentation. I've sometimes used JADD on unfamiliar code to make it easier to digest. With my own code if I can't determine a function's purpose from its name and the names of its parameters I consider it a code smell and refactor it until its blatantly obvious.
ReplyDeleteKenneth Cochran You raised some important questions: 1) Why document API? 2) How to document source code? 3) How to generate documentation? For the last two questions, Documentation Insight is definitely a nice tool. For the first question, I think that depends on your situation. If you are API library developer or component developer, Documentation Insight will be your sweet buddy :-)
ReplyDeleteKenneth Cochran You won a V1 license, would you like to check out the new features/enhancements introduced in V2?
ReplyDeleteBaoquan Zuo It is nice to document return values on border conditions and special situations, error handling, exception handling, used pattern for work with class and other questions. Delphi lacks straight and safe strong/week reference management (which problem have been solved in most other languages), so it is important to declare which object owning pattern is used. Today i have lost 5 minutes on invalid pointer crash with x:=TXMLDocument.Create(); x.SaveToFile('yyy'); FreeAndNil(x) "invalid pointer operation" crash :). It is too sad when class MUST be casted to interface to work :)
ReplyDeleteAlexey Petushkov Also including special parameters :) That will definitely save time for both ourselves and other team members.
ReplyDeleteBaoquan Zuo Yes, I can see documentation being useful for someone developing a public API. I still feel the best documentation is expressive code. Supplementary documentation can easily get out of sync with the code if a team isn't disciplined enough to update it. This is true no matter how easy and convenient the tool you use to maintain it is. I reserve code comments and external documentation for situations where the code simply can't express my intent to my satisfaction.
ReplyDeleteKenneth Cochran Yes, I understand your situation. I think an expressive code/design is a MUST and a well-explained documentation when necessary is a nice addition, no matter where they are and what they are. :-)
ReplyDeleteKenneth Cochran While expressive code makes it easier to understand "what" is happening, it doesn't always explain "why" it is being done. This is where source code documentation can really help.
ReplyDeleteIn the context of a complete system/application, knowing "why" the code is doing "what" it does can be very helpful to a developer, especially if they're not the original author of the code.
I do agree that keeping documentation up-to-date can be difficult and requires discipline, but this is true of all documentation, not just what may be found in source code.
I use doc-o-matic express, which is free and generate very nice HTML documentation compared to the one generated by IDE's Model View
ReplyDeleteCode site Express that comes with XE2 is very good
ReplyDelete