Strategy in Comments, Tactics in Code

in reply to The art of comments: (rave from the grave)

One, I have a rule I teach to any programmer under my supervision: strategy in comments, tactics in code. Tactics are what you do to get something done. Strategy explains what you want done. In warfare, an officer focuses on strategy: "secure that hill!" "pick the best two devices!" "find the local minimum!" Don't mention the tools you use to get that job done, soldier, unless you're being fiendishly clever. Comments should be in natural human language, while the code should just accomplish those tasks.

Two, I have a technique I teach to any new programmer, whether they're under my supervision or not: write the comments first. Programming courses always talk about writing pseudocode: why write it on scratch paper, just to throw it away?

sub process_ring_packet
{
    # if we have a prior server registered,
        # if this packet was received from the prior,
            # if this server created this packet originally,
                # kill the packet, it's completed the trip.
    # scan the packet for all object references.
    # dispatch packet to object mentioned which we control.
    # if any object references remain unhandled,
        # if we have a next server registered,
            # send the packet to the next server.
}
[download]

Once the pseudocode is written in human terms, then fill in your actual code in whatever computer language is being employed. Note that I didn't say HOW to do each of the tasks in the comments. I just wrote what needed to get done.

Lastly, as others have indicated, the actual code should not be too clever for your teammates to understand at a glance. Use clear concise words for variable names, without abbreviating them unnecessarily. Use the idioms they're familiar with. Use the language they're familiar with. You shouldn't need any # swap $x and $y comments to explain basic tasks or idioms. If you really find a clever but unusual trick, or you need to hack out something that's not obvious, then you can mention it.

I have taught my editors to highlight tags like #REVIEW: #TODO: #BUGBUG: #HACK: so I can see areas that need more attention. Review things which may or may not be right or done in the best way. List things that are definitely undone but needed. Mark areas where known bugs are located, even if the fix isn't in there yet; give bug tracking numbers if appropriate. Mark code which is overly clever to get around dumb library limitations or which save a lot of processing in obscure ways.

--
[ e d @ h a l l e y . c c ]

Comment on Strategy in Comments, Tactics in Code Select or Download Code

Replies are listed 'Best First'.
Re^2: The art of comments: (rave from the grave) by Anonymous Monk on Jul 07, 2005 at 15:18 UTC
Two, I have a technique I teach to any new programmer, whether they're under my supervision or not: write the comments first. Programming courses always talk about writing pseudocode: why write it on scratch paper, just to throw it away? That leads to the archetypical example of bad comments: `$counter ++; # Increment the counter.` [download] Pseudocode gets replaced, not supplemented. It's thrown away because there's something better: the real code. Comments are not a replacement for pseudo-code.	[reply] [d/l]
Re^3: The art of comments: (rave from the grave) by halley (Prior) on Jul 07, 2005 at 15:44 UTC
I probably wouldn't use the word "increment" in daily conversation, so I also wouldn't write `# Increment the counter.` Incrementing is tactics, not strategy. I also didn't mention, but probably should, that right-comments are typically tags (`#REVIEW #HACK` etc.). Note how the pseudocode is indented as you might expect will be necessary while writing up the code. If a line of actual code is very close to the English description, which does occasionally happen when writing literate code, then the explanatory pseudocode can be removed. Let literate code speak for itself. -- `[ e d @ h a l l e y . c c ]`	[reply] [d/l] [select]
Re^2: The art of comments: (rave from the grave) by BrowserUk (Patriarch) on Jul 07, 2005 at 13:00 UTC
Again, I was really after live examples rather than wisdom. Not that your wisdom isn't good, just that I was hoping for a variety of opinions back by examples. Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error. Lingua non convalesco, consenesco et abolesco. -- Rule 1 has a caveat! -- Who broke the cabal? "Science is about questioning the status quo. Questioning authority". The "good enough" maybe good enough for the now, and perfection maybe unobtainable, but that should not preclude us from striving for perfection, when time, circumstance or desire allow.	[reply]
Re^3: The art of comments: (rave from the grave) by halley (Prior) on Jul 07, 2005 at 13:53 UTC
(1) You asked for examples of what we think are good comments; you didn't specify that they had to be live code published on the web but I guess that's all you wanted to see. With your followup, your tone sounds more like "show me that all the wisdom isn't just hot air, prove to me that people really bother to comment properly." (2) The pseudocode example I gave was directly taken from my real code; the actual code between the comments would not have contributed much to the discussion so I returned it to pseudocode form. Sorry, but 99.99% of the code I write is not published on the web, nor will it be. (3) You're welcome to browse http://search.cpan.org/ under Authors: HALLEY for three really small examples. Fair warning: these examples are so small and simple that the comments are almost entirely POD, not `#` form. Perhaps someday the example I illustrated will be published, since it's a meaty and tightly-knit component library of over 30 packages, and it has a LOT of weird code that needs commenting. -- `[ e d @ h a l l e y . c c ]`	[reply] [d/l]
Re^4: The art of comments: (rave from the grave) by Anonymous Monk on Jul 07, 2005 at 17:03 UTC
...I wonder if anyone would care to link to one or two examples... Actually, the OP was quite clear that he wanted links to examples, not inlined ones.	[reply]
Re^3: The art of comments: (rave from the grave) by jhourcle (Prior) on Jul 07, 2005 at 13:56 UTC
The problem is that it's difficult to find the ideal comment. It's easier to discuss what makes a good comment, or what doesn't, than to find a file that contains all good comments. It's much easier to come up with a contrived example, than to point to a file, and say 'the comments on lines 1873 to 1904 are great... of course, the rest of them suck'. We can't easily link to modules or such on CPAN, as they're bound to change, and so when someone comes back and reads this thread a month from now, the links might make no sense. If you're really in the mood for specific code -- I'll insert it here: Read more... (52 kB) The thing is -- there's a mix of good and bad comments. There's stuff in there that I said was bad (redundant comments), there's stuff that Forsaken mentioned (writing the logic in comments, then fleshing out the code), there's end-user documentation in pod, there's comments hidden from the pod, there's the comments that brain_d_foy mentioned (WTF Was I Thinking). By my quick count, it's almost 1300 lines total (blanks included), with about 400 lines being pod, 200 non-pod related blank lines, and 350 lines of comments. (leaving about 400 lines actually containing something useful ... although half of those are just for legibility) Update: blah...fixed typo in first line (does or _doesn't_)	[reply] [d/l]

In Section Meditations