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 -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers