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

In reply to Re: Documenting Methods/Subs by krujos
in thread Documenting Methods/Subs by vek

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.