Beefy Boxes and Bandwidth Generously Provided by pair Networks
Clear questions and runnable code
get the best and fastest answer

Re^2: The art of comments: (rave from the grave)

by Anonymous Monk
on Jul 07, 2005 at 15:18 UTC ( #473121=note: print w/replies, xml ) Need Help??

in reply to Strategy in Comments, Tactics in Code
in thread The art of comments: (rave from the grave)

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.
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.

Replies are listed 'Best First'.
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 ]

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://473121]
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others wandering the Monastery: (7)
As of 2017-11-20 04:17 GMT
Find Nodes?
    Voting Booth?
    In order to be able to say "I know Perl", you must have:

    Results (284 votes). Check out past polls.