Beefy Boxes and Bandwidth Generously Provided by pair Networks
Keep It Simple, Stupid

Re: Documenting Methods/Subs

by krujos (Curate)
on Jan 10, 2003 at 17:21 UTC ( #225872=note: print w/replies, xml ) Need Help??

in reply to Documenting Methods/Subs

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.


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

Replies are listed 'Best First'.
Re: Re: Documenting Methods/Subs
by Anonymous Monk on Jan 10, 2003 at 17:38 UTC

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

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://225872]
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others exploiting the Monastery: (5)
As of 2021-04-11 19:08 GMT
Find Nodes?
    Voting Booth?

    No recent polls found