in reply to Documenting Methods/Subs

Personally, I try to use self explanatory names wherever possible, use my ($various, $param, $here) = @_; for positional arguments, and generally try to write the code in such a way that such information is contained in the code wherever possible. This also impacts the surrounding code - if your functions and methods are well named, the code using them will also be easier to read. My maxime is that if you feel the need to add a lot of comments, then something's fishy about your structuring and naming style. Between the public documentation and the code, not much room should be left for comments on the code.

Write code with as few indentation levels as possible (but break this rule when it makes the code read more naturally), mostly using last and friends. Always name variables sensibly. Avoid having more than two or three subexpressions in a single condition. Do things Once And Only Once, so that you take up less screen space and end up with fewer but more expressive distinct things to understand. Capture regularities in code, irregularities in data. Do the tersest and simplest thing that can possibly work.

These and more, similar ones are the things to strive for when writing code. Follow them well, and you will find that even scarcely commented code is comprehensible.

However,

you should meticulously document your data structures. The clarity of the code hinges on your understanding of the data it manipulates. That is something you should pay very close attention to. In essence, good programming skills means good data structure design skills.

Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won't usually need your flowcharts; they'll be obvious.
-- Frederick P. Brooks, Jr., The Mythical Man-Month

If the data structures are well designed, the code to manipulate them will suggest itself. If they are well documented, the code that manipulates them will suggest its intent with hardly any commentary.

Makeshifts last the longest.

Replies are listed 'Best First'.
Re: Re: Documenting Methods/Subs
by castaway (Parson) on Jan 13, 2003 at 10:33 UTC
    I didn't mention anything about variable/function names etc. as I like to assume that every 'real' programmer tries to give sensible names to things to some degree.
    After all, if someone comes with code like this:
    my $a = $b - $c;
    When what they meant was:
    my $totaltime = $endtime - $starttime;
    Then a usual response would be 'go away and write it so you understand it yourself in a years time, and then ask me again when it doesn't work'.

    I agree completely about the data structures, the more so in perl where you can make hashes of arrays of hashes etc. I have some lovely ones which I wouldn't understand myself any more without the comments.
    C.
    *trying to maintain some code with 8-char indents, but thankfully sensible variable names and comments all over the place!*

Re: Re: Documenting Methods/Subs
by Wysardry (Pilgrim) on Jan 19, 2003 at 15:07 UTC

    I consider using descriptive variable and subroutine names to be a form of commenting/documentation.

    If you want your code to be easily understood by yourself and others, you do so. If you're trying to hide what you're doing, you don't.