Email not sent, because NO ONE COMMENTS

I just decided not to email this to the local standards keeper, as we set out on a new project.

---

I would like to suggest a standard that almost no one else is the world things is sensible: a developer coming to unfamiliar code should be able to understand it by reading the comments. In my view, the comprehension of code is like a transuranic element -- rapidly decaying, short-lived -- and that's in the mind of the coder. Expecting someone else to read code and simply get it is unrealistic. Oft times, the coder spent a lot of time figuring out how to code something; the code embodies business logic. When that thought process is not captured in a comment -- it vanishes. And it has to be in a comment in the code, else it will be lost. "We wrote that up in the functional spec, that's never been updated and we can't find it anyway." That doesn't work.

It doesn't take that long to type comments. We type for a living! The confusion and uncertainty presented by poorly commented code yields wasted time trying to comprehend code, and more time chasing down bugs introduced because of a failure to comprehend the code correctly. Comments save time.

I have heard of the argument that excessive commenting is worse than no commenting, because the comments get stale and are misleading. The easy answer to that is "Maintain the comments as you modify code." I would encourage people to comment excessively -- because if they lean in that direction, the chances are increased that they'll comment adequately.

A while back, I incorporated this standard in a automated code reviewer utility: it computed an estimated ratio of comments to code, and while there was no specfic ratio required, a low ratio made the coder suspect, and more likely to get dinged for insufficiently commenting during the real code review. The utility worked with enhancements, in addition to new code, because we applied the utility to the differences listing for existing code.

---

I write to deaf eyes, I know. No one comments. It mystifies me and makes me crazy.