Re: Documenting Methods/Subs

[krujos]

Commenting subs/methods are the something I feel that everyone should do. Those comments save me tons of time every day. Commenting in the code is nice as well (an I am not implying that one should be done in favor of the other, do both), but if I just want to use a sub that someone else has written I don’t want to have read the code to discover what it does (some time the function name is just not enough) and what I need to pass to it / what it will give back to me. This is what comments at the beginning of subs are for. From an ease of use standpoint, I don’t have to guess at what the sub does and I don’t have to care about how it does it, I only have to know what to give it in order to use it. This encourages code reuse because it makes the function easy to use. Comments in the code don’t really provide this abstraction for the programmer who has to come along and use these functions.

Another point about inline comments is that they don’t really provide a general overview of what the function is doing. Inline comments are more often to document how something is done and explain trickery for certain lines / small blocks of code, not give an overview of the whole function. With a header comment you are forced (well sort of anyway) to do that. A general synopsis of a sub, its parameters and its return values is invaluable, epically in a large program that more than one person works on. Think how frustrating it would be to run into subs doing shifts all over the place to get parameters and such. One header comment about the required parameters and everyone else who uses the code is spared that work.

All that said there are thousands of trivial subs that do exactly what the function name describes and are all of about five lines long etc… These proably do not need super indepth comments, but I still think it’s a good idea to comment these as well. Small subs are obviously less likely to confuse people (most of the time) than a huge, possibly epic sub.

Josh

UPDATE: After lauging my arse off at the AM reply I have decided to make it a little more readable
 My $.02

[Anonymous Monk]

On the topic of clarifying things, breaking text with paragraph tags helps too ;-)