It's not a black & white thing. I think that both those that document all subs and that document none are wrong. Good programmers know which subs to document and which subs can be left undocumented. ;-)

Abigail

++!! This is the method I use as well. There are a few other guidelines I use:
• More than 2 args, document the args so I remember what the hell I'm doing when I come back to the code in 6 months :)
• Keep it short enough that a programmer can figure it out, and it doesn't take up to much screen space. If you need more than that, it should probably go in the help section.
  
  With that, and common sense, it is usually pretty obvious to me what I need to put in th comments.
  
  "Nothing is sure but death and taxes" I say combine the two and its death to all taxes!

This is actually a good reason to use a module like Params::Validate, it helps provide documentation for a subroutine/method.

For example:

 sub do_the_thing
 {
     my %p = validate( @_, { foo => { isa => 'Foo::Big' },
                             size => { type => SCALAR, default => 10 },
                             ...
                           } );
     ...
 }

This way all the possible named arguments are documented, as well as their types/classes, defaults, etc. Along with good names, this really does completely document what parameters are accepted, _and_ as a bonus does actual validation on them.

I'm not actually that much of a fan of enforcing object types in method signatures to be honest because it can lead to a certain amount of pain at testing time, especially if you're using the very lovely and worthwhile Test::Class. The 'Self Shunt' testing pattern is remarkably handy, that's when you do:

sub test_the_thing : Test {
    my $self = shift;
    ...
    $object_under_test->do_the_thing( foo => $self, ... )
    ...
}

sub called_from_do_the_thing {
    my $self = shift;
    ok array_eq(\@_, [qw/foo bar baz/];
}
[download]

and similar tricks. If you're enforcing the object type you have to draft in Test::MockObject, which is great, but is also substantially more complex.

There's one file I'm working on right now that has every single function extensively documented with POD. I hate it, cause it gets in my way of seeing the whole code. But, when I first started working on it, it gave me a smidge of insight into what the author was thinking. (Granted, it's only a smidge cause the author sits about 50 feet from me, but it would've been a heck of a lot more if the author wasn't around to ask questions of.)

I guess that if the person after you can ask you questions, don't comment it. If the person after will not be able to ask you questions, comment evey single assumption you make. YMMV.

------
We are the carpenters and bricklayers of the Information Age.

Don't go borrowing trouble. For programmers, this means Worry only about what you need to implement.

I guess that if the person after you can ask you questions, don't comment it.

I have to disagree. What if you leave the company? What if you get run over by a bus? What if you decide to go on vacation (heaven forbid!) and trek around the Himalaya for two weeks?

Even if none of that happens, what happens when the code ships and gets forgotten, then someone decides to dust it off three years later? It's ancient history; will you really remember what you were thinking when you wrote it?

I suppose it's possible to go overboard with documentation, but I guess I find it much easier to ignore something that is there than to fill in something that isn't. I rarely trust myself to be able to remember my own thought process a couple of years down the road, let alone reconstruct somebody else's.

        $perlmonks{seattlejohn} = 'John Clyman';

What if you get run over by a bus?

Maybe my tongue was a little too far in my cheek. *winces* I firmly hold that the "Bus Number" of any group should never be 1. (And, if anyone can come up with a link that doesn't involve TWiki re: Bus numbers, that would be great!)

------
We are the carpenters and bricklayers of the Information Age.

Don't go borrowing trouble. For programmers, this means Worry only about what you need to implement.

I'm in the habit in the shop I work at of not commenting subs, unless they're very long and it's not obvious from the name or the routine itself what they're doing. Having said that, though, at my Uni it's expected that all subs are commented in depth, and I therefore do commment them there.

It's normally a fairly safe assumption (in my mind) that someone working at the same place you do, with a grasp of what's going on with the system and what the script as a whole should do can figure out what a specific sub is doing (especially if it's well-named).

I guess it depends on the people you work for (or are coding for, in the case of Uni) too .. and on their coding standards (or lack of) .. how much of a personal choice you get then is very much controlled by that.

Just a few quick thoughts ..
-- Foxcub

One of the things to remember, epically about the work place is that it costs other people time ( and the company money ) to have to go through a sub that is not commented. Just to figure out if it does what you want. When many people work on a project, epically a complex one that is potentially days of man-hours wasted because the original developer didn't feel it was important (or just plain didn’t think about it) to comment his sub. This can also lead to other things like many subs doing the same task (because other people didn't want to figure out the code) etc... As ridiculous as this sounds, I have run into it several times at my current job.
Sorry one of my pet peeves is not commenting code other people will be using.
Josh

=head2 returnName

=cut
[download]

Comments are not documentation -- or comments are documentation for the developers of the API. The users of the API should refer to the user documentation (the pod).

Comments needn't truly be comments (=for comment ...=begin comment ...)

I heartily disagree Abigail's comment that people who document every sub are wrong. There is no such thing as too much documentation, no matter how redundant it may be.

Lack of documentation is almost always wrong (programmers should not resort to sourcediving to learn function names).

MJD says you can't just make shit up and expect the computer to know what you mean, retardo! ** The Third rule of perl club is a statement of fact: pod is sexy.

There is no such thing as too much documentation, no matter how redundant it may be.

It can get to the extreme, very easily. Consider a simple sub to commify a number, called commify_number. There's no need for this to have a description of what it does - it's obvious. Large blocks of comments (or comments documenting most of the lines of code within the sub) for something like this are going to obscure what should be a relatively simple thing.

My thoughts: if code is getting lost in a sea of comments, there's too many comments. Redundancy is largely irrelevant if the comments themselves are stopping you seeing what's going on.

While I agree that a lack of docs is bad, it's very important to get some sort of balance between code usability (in a maintenence sense) and understanding, at least in my mind.

-- Foxcub

I agree, but with some clarifications.

When speaking of documentation, I mean things that document the particular module, philosophy, code snippet, or whatever the documentation is related to. If someone starts documenting how pack() works in the middle of the code or API then he's just lost track of what he's doing.

However, there seem to be couple of misunderstandings here between fellow monks. Some speak of documentation, some speak of commentation, and some speak of commentation as documentation. Naturally, disagreements will arise.

I usually wouldn't refer to comments as documentation. If someone says "look in the documentation" I certainly don't look for comments. I say that there can be too many comments, but too much documentation has never hurt me--as long as it has a sensible structure. If you end up with a long documentation with lots of examples and explanations in it you'd perhaps should start thinking about writing a separate tutorial or extract the examples to an own section. Has anyone ever complained about too many examples?

For modules this means that you first document the most important things so people quickly can use your module. But towards the end of the documentation you very well can put a more detailed explanation and give examples to illustrate special features, nifty uses, or gotchas. If it's a "funky" module, i.e. it does something technically advanced with Perl itself (constant.pm to take a well-known module) it can be interesting with a little explanation or forward to documents explaining how the module achieves what it does so the reader gets a chance to learn and understand rather than being a simple user. This certainly can help the module author with finding bugs or even receiving patches. It also feeds for further development and other related and interesting ideas. So no, I wouldn't say that there can be too much documentation. (Remember that I don't count a pack() tutorial in the middle of code as documentation.)

Just my thoughts,
ihb

how else would you know what your API consists of?(it shouldn't be magic)

I agree, and that is what POD is for. Remember that a lot of programs/modules have POD at the very end of the code (I've seen my fair share from the CPAN). As a programmer who wishes to learn the API I can do a quick perldoc foo and (hopefully) get everthing I need. I was referring to code where every method is documented by the type of comments I showed in my root node, including those private or debug methods of a class which won't be in the POD.

-- vek --

I heartily disagree Abigail's comment that people who document every sub are wrong. There is no such thing as too much documentation, no matter how redundant it may be.

Abigail's a pretty smart person, and I think the slip from "comment" to "document" was unintentional. Yes, you should always document your whole public API. Otherwise it's not really public, is it?

But don't waste my limited screen real estate on crap like this:

  #
  # Class->foo() - returns the value of foo for the object
  #
  sub foo { $_[0]->{foo} }

Another commenting pet peeve:

  # if $x is bigger than 10
  if ( $x > 10 ) {
      # set $x to $y modulus 50
      $x = $y % 50;
  }
  # otherwise, if $y is not equal to 50
  elsif ( $y != 50 ) {
      ...
  }

Argh! I hate that so incredibly much. Comments that simply tell me _what_ the code is doing are absolutely, utterly useless. Always assume that the next person does understand programming logic, assume that they understand Perl, etc.

Don't assume they know why something is the way it is, however. In the above code, I want to know why it's important to set $x to the $y modulus 50 only when $x is greater than 10.

There are a few exceptions to the "no walk-through comments" rule. Very complicated algorithms may deserve very careful step by step comments. This can help you as you code, in making sure that you're actually following the algorithm, and it helps future readers. And if you deliberately write less-than-clear code, for example as an optimization (after benchmarking and profiling, please), then it may be worthwhile to comment the what of the code.

But a good rule to follow is that if you think the what of the code is too hard to follow without comments, then you need to rewrite the code in a clearer manner.

There is no such thing as too much documentation, no matter how redundant it may be.

Whew! Obviously you haven't seen the code I have.

use warnings; # turn warnings on
use CGI;      # use Stein's CGI.pm for parsing params

my $q = new CGI; # create the CGI.pm instance

# get the customer's name (in the name parameter)
# place in in variable $customer_name
my $customer_name = $q->param("name")

# if the customer's name is "Bobby"
# print "Hi Bobby"
if ($customer_name eq "Bobby") {
    print "Hi Bobby\n";
} else { # if not, print "You're not Bobby"
    print "You're not Bobby\n";
}
[download]

Get the point? This completely distracts from the code and takes way more time on the part of the programmer.

As for subs, I say one comment directly above them. Anymore and the sub is too long and should be broken into multiple subs.

There is no such thing as too much documentation, no matter how redundant it may be. Lack of documentation is almost always wrong (programmers should not resort to sourcediving to learn function names).

Lack of needed documentation is always wrong - however over documentation, in my experience, can cause problems. For example:

• Excessive documentation/comments can be an excuse for poor code. Rather than spend the effort to produce comprehensible code certain developers will write a long and complicated piece of text to justify their technique. It sounds weird I know, but I've come across it enough times for it to become a personal anti-pattern I keep an eye out for.
• People change code and do not change the comments/documentation. The more redundent documentation there is the worse this problem gets.
• Documenting to early. If you're in an environment where the code is changing rapidly, methods and classes are being refactored and moved around on a daily basis, etc. then time spent documenting and commenting is wasted time.

Personally, I tend to go for development environment with common code ownership and require unit tests for everything. I find this removes most of the need for comments and heavy API documentation during development.

If the team discovers a need for documentation during development then we do it. If the team is not in-house then we will also have appropriate levels of design & implementation documentation as a deliverable (and we'll do it properly too :-)

This has worked well for me with smallish projects (about a dozen coders max).

All methods must be documented

Round objects!

And so do I. Whilst I take your point that it's generally a good idea to document the methods that make up your public API, those methods will not be the same as the full set of methods to which an object responds.

Anyone who works with your code needs to see documentation covering how you expect the code to be used (though I'm as guilty as the next man of failing to do this on one of the major projects I'm working on, partly because the API is still in flux). Anyone who works on your code should be using the source like God intended. And if you're not competent to write clear code then what on earth makes you think you're competent to write clear comments in a far more ambiguous language?

There is no such thing as too much documentation, no matter how redundant it may be.

Yes there is. I'm working on replacing some programs right now that stop every 5 lines or so with 20 lines of comments. Just document the subs if it's not obvious from their names, then document anything you do that's clever but obscure. Anything more gets in the way of following the code, which is The Ultimate Documentation.

If it's not (e.g. a hairy regexp, or an effective but maybe-too-advanced-for-your-colleagues Perl idiom), a comment is useful. Or, if the code is too opaque, a comment can provide guide to what happens.

But there are other cases.

Why you do things are sometimes not obvious. Or it may be obvious to you, but it won't be to the maintenance programmer (that's you, in six months). But why is different from what. Code the what and comment the why.

Some things are by definition not obvious. The interface (what you have in your example) should be explicitly documented for two reasons; it defines what the method/function actually does, and; before using a method you shouldn't have to spend time to understand how the code works, only what it does. And with a weakly typed language like Perl, it may not even be possible to deduce what kind of object to pass a method just by reading the code.

The following example is from a program for replicating subsets of a Wiki to other Wikis.

=head2 replicateSelection()

Replicate the selected pages in the local oWireLocal to this
remote Wiki, if appropriate (i.e. this remote Wiki owns it).

Return 1 on success, else 0.

=cut
sub replicateSelection { my $self = shift;

    logDebug("Replicating to (" . $self->urlWikiRemote() . ")");

    for my $name (@{$self->oWireLocal()->raNameSelection()}) {
        if($self->rhNameOwner()->{$name}) {    #Do we own this page?
            $self->replicatePage($name) or return( logError("Could not
+ replicate page ($name)") );
        }
    }

    return(1);
}
[download]

From the same program:

=head2 raExtractNamePageRecent([$html])

Return array ref with names of recently changed nodes/pages. 
Order: unique, most recent first.

If $html isn't passed, get the input from the Wiki.

Return undef on errors.

=cut
sub raExtractNamePageRecent { my $self = shift;
    my ($html) = @_;
    defined($html) or $html = get( $self->urlFromName("RecentChanges")
+ ) or return(undef);

    my @aName = ($html =~ m|&nbsp;</td><td><a href="[^"]+">([^<]+)</a>
+</td>|gs);

    #Already unique, because they are unique on the web page
        
    return(\@aName);
}
[download]

I find it very useful to write the interface before coding the method. Yes, I know pretty well what I intend to accomplish when I start out, but writing the POD first gives me ten more seconds thinking about the problem, including the important things like what goes in and out, what boundary conditions there are, and how to handle errors. I wish to think that this improves the quality of the code.

Documenting the interface using POD instead of Perl comments makes is easy to extract the class definition programmatically, e.g. using (warning, shameless plug ahead) Perl Oasis:
http://www.bahnhof.se/~johanl/perl/Oasis/pic/screenshots/image017.gif

/J

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.

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

#####################################################
#       RE: documenting methods/subs                #
#       version 0.01                                #
#       This note can be distributed under the same #
#       terms as perl itself                        #
#####################################################

# paragraph 1
# This is my opening statement where i state my 
# opinion on the afore mentioned node.

personally i go for more of a 'tabbed comments to the 
right hand side of an ambiguous statement' Camel-type 
documentation.

# paragraph 2
# some expansion on already stated opinions, and a
# little funny for some light relief

As you say, self-documenting is best - ideally there should 
only be a need to briefly "comment" or refer to other parts 
of the code. Otherwise, you probably dont know have a clear 
concept of the what and why of what you are doing - in which 
case, might as well keep schtum!

# paragraph 3
# my conclusion as to why code written in this format 
# completely sucks and makes no contribution to coding 
# productivity or ledgability

IMHO, using TAB/space to line up common features, liberal use 
of newlines, and well named subs/variables is usually more than 
sufficient to make code readable.

1; # PS i really hate it when people comment on 1;
[download]

There are basically two cases I work with for subroutines:

1. Methods in a class
2. Subroutines in the actual program (often calling a centralized class)

For the first, I always document everything with POD, except for private data. I think that someone using an object should never have to look at the actual source code, so it has to be documented, no matter how trivial.

Subroutines in a program are different. If someone wants to use those, they have to be digging through the source anyway. Most of the programs I write are CGIs, and go through a simple set of subroutines almost every time (set parameters, validate parameters, read or write a database, print the results or an error message). The subroutines that do this job are given obvious names (set_params, validate, read_db/write_db, print_results). It seems silly to document these with a subroutine header. However, a CGI that needs something beyond this will have its additional subroutines documented.

My favourite 'Comment the d*mn code' experience happened a few years ago - a frustrated workmate swore loudly and vociferously complained that so-and-so never commented his code and that he was fed up with trying to figure out what it was meant to do!

I walked over to look at the code over his shoulder, just as so-and-so sauntered across and said… 'Hit Page Down'

There were about three screens of comment explaining what was going on, why, and what was going to come back - pretty clear and detailed.

The angry chap harrumphed, and proceeded to read (slowly…) through the code, highlighting each line as he read down, to make it easier to see (he was a long tooth contractor…).

'Well - ok! Sorry' he said when he reached the bottom. He then pressed the Enter key, replacing all those lovely comments with a blank line, and blithely proceeded to make his code modifications…

We had finally figured out the answer to that song - 'Where have all the Comments Gone?'

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.

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;
[download]

When what they meant was:


my $totaltime = $endtime - $starttime;
[download]

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!*

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.

Initially my answer was going to be "It depends on the size and complexity of the code" but then I stopped and thought for a moment.

If a program contains subroutines, then it is a fairly safe bet that it is big or complex enough to require comments. After all, very few people use a subroutine in a 3 line program. ;)

If it doesn't all fit on my screen without scrolling, then adding comments provides visible breaks in the code making it easier to find a specific section.

So basically I add at least one comment to each subroutine (stating what it does on a single line) to make it easier to spot if and when the program gets larger.

If I used some really hairy code - or something just plain weird - I'll add more detail, though not to extremes.

I find it makes life easier that way - especially if I have to edit the code several months later or decide to reuse that subroutine elsewhere.

You might be interested in this node, where I discuss some tests I wrote that do exactly that :-)

We are looking for another Perl developer and are issuing a code test, if there aren't any comments in the code we 1: ask why and 2: put the resume on the bottom of the pile.

The primary reason is that a job interview (and the code that goes with it) should be the _best_ that you can do. I'll probably be the one tracking down your bug at midnight and uncommented code makes me very unhappy..

(of course the 'you' in the above is not being directed to anyone specific)..

Just because someone _thinks_ that their code is self commenting doesn't mean that they are correct.

Just because somebody _thinks_ that their comment explains the code doesn't mean they are correct :-)

Bad comments are just as evil as bad code. In fact they are worse, since you then have the problem of what is correct - the code or the comment.

I'm not anti-comments - but they do have problems of their own which are often unacknowledged. Over the years I have found self-documenting code (tests, assertions, etc.) to be of more use in many, if not most, instances.

I would also ask the coder why they didn't add comments - but I would see if they had sensible answers before consigning the resume to the bottom of the pile :-)

I agree with you but I think you misunderstood my root node. I don't think you'll find many good arguments against comments in code. Comments should be used to explain why something was done a certain way or to explain a complicated alogorithm. The purpose of my root node was to ask opinions about comments prior to subroutines/methods decribing their purpose.

-- vek --

=cut
--Brent Dax
There is no sig.

In code I write for myself (primarily), I usually do something like:

sub blahfasel
{
    # This function does XYZ
    # Parameter: This, That
    ...
}
[download]

I keep meaning to learn POD and add that, but it won't be as a replacement for comments, just to provide an overview how to use the modules without having to look at the code.
C.

Personally I comment when I think it needs a comment :-)

My commenting style has gone from none (long, long ago when I was young and innocent), to far too much (after the first few times I had to maintain somebody else's code :-), to what is hopefully a happy medium.

I've noticed in recent years that things I would have previously elucidated with a comment I now explain in other ways. For example:

• I write a lot of tests.
• I spend a lot more time and effort on the naming of variables and methods.
• I spend a lot more time refactoring code for clarity and ease of understanding (as opposed to functionality or efficiency).
• I use assertions, preconditions, postconditions and other design by contract techniques.

These have an advantage over textual comments because (apart from naming) they cannot get out of sync with the code base.

If i'm going to comment my code (which i only do for something which others will have to see and/or maintain) than i use the following setup which i have derived from my coding experiences:

##
# Function: get_input
# Receives: nothing
# Returns : user input regarding previous menu, Taint checked and chom
+ped.
# Notes   : none
##
[download]

Anyway, there's another $0.02 for your hat,
jynx