The Purpose of Commenting

[chromatic]

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.

[I0]

I find the most useful comments state what remains invariant, while the code states what gets transformed.

[tilly]

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.