Re: Comments

From: Kristofer Skaug (ya.ierfgnf_at_thnxf.x)
Date: 06/23/04 

Date: Wed, 23 Jun 2004 12:05:50 +0200

Scout wrote:
>
> What rules do you use in deciding what (and what not) to comment?

I like your heuristics as a starting point ("must-have" commenting
situations).

Myself I tend to comment rather more than less, when in doubt. I have too
many times noticed that "simple, obvious" things (to me) are far from
obvious to a colleague who has to jump in and fix something in my code.
Of course I don't mean stupid things like "inc(i); // increase i by one"
type comments; but rather the goings-on at application levels higher than
that - there's plenty of medium-to-high-level stuff that warrants an
explanation.
For example, the allocation cycle for a global (or class-field) pointer:
Where is it allocated, where is it freed? How is the "soundness" of its
life cycle guaranteed? How is this memory buffer access protected
(multithreaded access)? etc.

So as time allows, I try to explain what my code does (the design behind
it) in unit headers; example usage; etc (if it's a reusable class). Also,
I am fairly pedantic about commenting each procedure/function with a
header that describes its interface (contract) as accurately as possible.
After all, the contract is often not really obvious from the code; and if
even you think it is, it could still be the "wrong" implementation
(incorrect w.r.t. its specification). What are the assumed and validated
preconditions? postconditions? error cases? side effects? etc.

It should be clear that simple GUI code (e.g. menu- or button-click
handlers) will never be exhaustively documented in this respect ("dear
code reviewer, let me explain to you how we don't give a bleep what
"Sender" is, in procedure TForm1.StartButtonClick(Sender:TObject), and
why you should be glad that we don't waste your time...").

At the final "end;" statement of each procedure I generally insist on
using a 'trailer' comment reflecting the procedure name on so as to
improve visibility when you approach a function "from below" (scrolling
up in the editor). This being done, it is less important to try to
"conserve vertical real-estate" for the purpose of viewing as much code
as possible in a single screenful.

In fact, I have over the years increasingly moved away from this
objective (e.g. being more generous with line breaking and full-block
comments, whitespace to clearly separate distinct code blocks etc) and
now try to promote readability and testability of the code (e.g. some
code coverage tools having issues with multiple statements on a single
line). 

-- 
Kristofer