Let me add a verbal ++ to the above. I've found (over lots of years of experience), that if you can't express it in pseudo-code you probably don't understand (or don't completely understand) exactly how you're trying to approach the solution. There are lots of times when a lack of being able to express something (completely) in pseudo-code led me to the conclusion that I didn't adequately understand the interfaces I was dealing with and the way I needed to manipulate things.

The really retentive will then go through after the fact and add in the "why" commentary to supplement the "how" pseudo-code. Or, as a button I own says: "Code as if whoever maintains your code is a violent psychopath who knows where you live."

My all-time favorite insight comments remains Re: The Purpose of Commenting. My personal understanding of what I0 said is the style I described in some detail at Re (tilly) 4 (disagree): Another commenting question,. (That is a semi-unfortunate thread. While I like it for the comment, The public posts were paralleled by a series of private /msgs that were more friendly than the public record. I refer back to it because among other things it captured detailed thoughts about why I coded as I did right after I wrote it. But I regret the one-sidedness of the exchange.) I have been happy with that compromise between comments and code for a while now. Comments serve a purpose that code never can. But what you can communicate by coding well, you definitely should.

(In fact when I next experiment with my coding style I am likely to try commenting less than I do now.)

There's a middle ground. The path to it starts by considering that comments have the potential to be a maintenance burden. The potential for burden increases with the volume of commentary. It gets to be a major nuisance during maintenance when a 2 line change means having to rework 20 lines of commentary. Human nature being what it is, somebody is going to forget to update a comment, and the world described by the commentary can begin to diverge from the truth of the code. Having two divergent stories is a bigger liability than one truth, the code, with no commentary at all.

Pod documentation carries an additional risk, if one follows the style of locating the pod either entirely before or entirely after the code it describes. Physical distance between code and its corresponding commentary increases the likelihood that the commentary won't be updated during maintenance.

The middle ground is to locate commentary close to the code it describes, and to write as little commentary as necessary. If comments are close to the code and there isn't an excess of verbiage, chances are greatly improved that the commentary will survive maintenance.

There was a thread at Inline POD vs. EOF POD a while ago about the joys of inline versus eof POD. While a lot of people seemed to like inline, my strong sympathies go with the position put forth by tye and Abigail that eof is better for POD.

In particular I liked Abigail's explanation of why inline is a problem. To it I can only add the point that synchronization of POD and code should be far less of a problem than synchronization of general comments and code. The POD is about the public interface. Public interfaces should not be changed as capriciously as code. If you do change them, you need to track down all of the code that used the old interface and change that as well. Compared to that synchronization, modifying the POD is a small cost.

Comments that need synchronization with code for me go inline. There your point about distance is relevant. But I strongly prefer having POD at the end of the file.

1. Comments should say why you're doing something, not what you're doing something
2. You're never coding something for yourself, but for the coder who will be maintaining it in the future.

If things get any worse, I'll have to ask you to stop helping me.

me too... document the hell out of methods; try to make the code within the method self-documenting by judicious use of descriptive variable names, and comment whatever isn't obvious.

guess my complaint about POD and Perl is the lack of a more precise documentation markup/syntax. With POD, one can only really =head and =item and such, but what i think we really need, especially in a weakly typed language like Perl is something more like:

=public =object =method get_name

=usage  <string> $name = $this->get_name();

=args  <none>

=returns $name

The current user's name.

=description

Basic accessor method to get user's name.
 
=cut
sub get_name {
    ...
}

...and then someone (me!) could write a parser which would be able to create beautiful, standardised, perl doco for every module under the sun, rather than the diverse, often terse, sometimes overly verbose, and occasionally obscure doco that exists for modules on CPAN...

just a wish... (thoughts turn longingly to function prototypes in Perl 6...)

d_i_r_t_y

Absolutely not.

This is a maintenance disaster waiting to happen. When the functionality of the code changes, either the comments stay in sync through prodigious efforts of discipline (that I, in 18 years of coding, have yet to encounter), or the comments drift away from what the code actually does. Hence the dictum:

Debug the code, not the comments.

That is not to say that such information is not useful, quite the contrary. But it should be extracted by programmatic a posteriori source code analysis. Think lint. Relieve yourself of work that you can get a compiler to do for you.

And then there's the issue that this is eight lines of comments for what is probably one line of Perl...

--

g r i n d e r

I've moved from "comment the hell out of everything" to "write obvious code and document interfaces and data" over the past six months or so (yay code review!). It took me about three years to get from "comments aren't really necessary" to "comment the hell out of everything".

When I started working at Advanis, I'd document every block, and often every non-trivial line of code. The other programmers who looked over my code objected, saying that instead of writing comments, I should be writing more lucid code. I scorned them: good names are difficult to come by. They warned me that lengthy comments concerning the "what" and the "how" would quickly become obsolete and misleading. I scorned them: I saw myself as a disciplined, meticulous programmer who would never let that happen.

You've all seen this coming: about a month later, during one of my code reviews (arrogant and obstinate though I was, I wasn't dumb enough to spurn code reviews) with one of my block comments circled in scary red ink. The comment was completely at odds with the code (which I'd changed in a hurry during a rather stressful evening debugging run). And the student was enlightened.

My current project is a large module (large relative to the other ones that I've written) that I hope will appear on CPAN someday. My current approach to documentation is to describe the interface to each function in POD immediately above the function: this takes care of user and programmer documentation all at once, and involves less repeating of information. (And it seems that I'm finally starting to understand what Pike meant when he said "put the complexity in the data, not the code", so the code's simple enough that it shouldn't need documenting... but that's for a code review or three to determine, I guess.) We'll see how well that works.

--
:wq

• It is far more often the case that there is not enough documentation.
• It is usually easier to make 'too much' into less than 'not enough' into more

hsm

It is my opinion that Perl would be well served by adopting a documentation tool/format with a similar level of features. The links really help developers get familliar with the project quickly, the generated hierarchy diargrams and collobration diagrams really aid in understanding object hierarchies.

There has been some talk about this for Perl6

Kyle