Re: commenting, was Re: Use of declare blocks

["Randy Brukardt" <randy@rrsoftware.com>]

<tmoran@acm.org> wrote in message
news:GYydnepKEqaRFJnbnZ2dnUVZ_uqvnZ2d@comcast.com...
> > Wherever I wanted to be able to expand the source code
> > with additional documentation, I included a
> >
> >        --{file-name}
>   My problem is that I don't go back to yesterday's code that wasn't
> throw-away after all and comment it, or go back to last month's library
> routine that was easily readable by anyone working in last month's
> context, and expand on its comments.  I would have to be forced,
> or at least "re-educated".

I find that going back and expanding comments is a fool's game, because by
the time the need is obvious, it is too late to do a good job (at least
without wasting a lot of time relearning the code in question).

Here's what works for me:

(1) Throw-away code doesn't need to be commented, but then it must be thrown
away. That means immediately. I find the latter hard, so I hardly ever write
throw-away code (most of it is still on my computer somewhere - or on one of
my older computers...).

(2) Code that isn't likely to be used frequently gets commented in critical
places, and every subprogram gets a basic description. I use good names and
the like, so it will be possible to figure it out again in the future. After
all, a lot of Ada code doesn't need comments if the entity names are decent.

(3) If I find myself working on/reusing older code, if I find the comments
inadequate, I immediately improve them so that they make more sense. (Once I
figure out what is going on, of course.) Once you've used something twice,
it's a pretty good bet that you'll use it a third time - so don't even think
about delaying about improving the comments and other documentation. After
all, having insufficient comments the first time is understandable; it isn't
possible to predict what will be hard to understand in the future. But once
you have an firm answer to that question, failing to act on it is silly and
unprofessional.

If you really wanted to be forced to do something, it should be to throw
away throw away code. Keeping it around is more likely to be harmful than
helpful (especially if it is totally uncommented).

                                    Randy.