Beefy Boxes and Bandwidth Generously Provided by pair Networks
Just another Perl shrine

The Purpose of Commenting

by chromatic (Archbishop)
on Jan 18, 2001 at 12:04 UTC ( #52725=note: print w/replies, xml ) Need Help??

in reply to Re (tilly) 3: What you want and perl advocacy gone way wrong
in thread module info

Yes, you're a good coder and you write clean code. There's very little you'll release to production that I can't figure out mechanically, and vice versa.

There is, however, a great difference between understanding *what* you are doing and *why* you are doing it. This applies when working around bugs, when implementing business rules (which have, at best, a rather tenuous and dispassionate relationship with what we would call reality), and when doing things one way instead of another.

How else will other good coders distinguish between personal preference (using defined tests on variables instead of oring them in place with default values) and operations and assumptions necessary for your code to work.

I will only mention mere mortal programmers in passing.

Having recently come up to speed on a large and complex and evolving codebase with minimal documentation and no further hints as to its name and nature, I will repeat that understanding the mechanics of a program is rarely beyond the abilities of your average caffiene-stymied simian.

It is only discerning the will and the intent of the programmer that allows you to proceed without fear. That means coding by intent, expressing the design by way of metaphor (of which descriptive names play a part), and that means commenting your code with the assumptions you make and the reasons for any non-obvious decisions.

Replies are listed 'Best First'.
Re: The Purpose of Commenting
by I0 (Priest) on Jan 18, 2001 at 20:15 UTC
    I find the most useful comments state what remains invariant, while the code states what gets transformed.
      Thank you.

      As always, you are short, accurate and insightful. It may take thought to understand what you mean, but that effort will be richly rewarded.

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://52725]
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others pondering the Monastery: (9)
As of 2019-10-22 13:29 GMT
Find Nodes?
    Voting Booth?