I think I've complained about this before, but:
When you are preparing a patch, fixing the comments is JUST AS IMPORTANT
AS FIXING THE CODE. Obsolete comments are worse than useless. Look to
see if you've invalidated something in the head-of-file comments about
the module you're changing. Look to see if you've invalidated something
in the particular function's header comment (in particular, if it has a
list of explanations of its arguments, for heaven's sake update that
list when you add or change an argument). Look to see if some block
comment within the function needs to be updated. If you are grepping to
fix all references to a function or global variable, do not overlook the
ones in comments. If you use a grep substitute that does not search
comments, throw it away and get one that does.
I've gotten tired of fixing other people's oversights in this regard,
including major committers who ought to know better (and do not have
even the thin excuse of poor facility with English). If we don't
maintain the comments adequately, we are hastening the decline of the
Postgres code base into an unintelligible, unfixable morass.
There, I feel better now.
regards, tom lane
