[Ayttm-devel] Re: Prefs window

[Tahir Hashmi]

[Repost: There were errors in sending last time, and I didn't get my
   mail back]

On Sun, 23 Mar 2003 12:50:30 +0530 (IST)
Philip S Tellis wrote:

> I don't know about that.  Whenever I plan on reading someone else's 
> code, the first thing I do is delete all the comments.  Very often the 
> code is newer than the comments.

Indeed, out-dated comments are worse than no comments. Perhaps, each
developer should follow a policy of ensuring that the comments are
updated before committing any file? Of course, it would be a burden
but it all depends on how much one is willing to do for good karma ;-)

> IMO, only comment code that is excessively obscure - if you can't 
> rewrite it that is.

Comments need not always document the workings of a function. Rather,
comments for source documentation *should not* include these details.
However, each function should document atleast the following:

- Promises:     What the function promises to do
- Requirements: What the function requires the caller to ensure (aka
  guarantees)
- Side-effects: The changes that the function makes to the program
  environment (changes in values of global variables etc.)

Variables, struct's or class'es should state their purpose of
existence in greater detail than is guessable from their names. These
are the things that are not easily tangible from the source code. For
the rest, there is Doxygen.

-- 
Tahir Hashmi
http://staff.ncst.ernet.in/tahir
Compact XML Alternative - http://xqueeze.sf.net