Re: Comments in code

[Warren Baird <photogeekmtl gmail com>]

Stephane Delcroix wrote:
> Hi Michael,
>
> I only can give an explanation on the lack of comments in the code I
> write, but here's why I don't write comments:
> - the code is easier to read than comments
> - the code never lies
> - with comments, it's really hard to keep code and comments in sync.
> - good names for methods and attributes speaks for themselves (or
> should)
> - i'm a bit lazy
> - the XP methodology says something like "if you can't understand a part
> of the code, this code should probably be refactored"


I think all of these things are great arguments for not having comments 
*in* code - i.e. within method bodies...

However, one thing that I have found while working on f-spot is I really 
 wanted more comments *around* the code...  I.e. in a situation where 
there are a few similar methods, indicating which one should be used 
under which conditions, etc.

This kind of higher-level comment doesn't suffer as much from the 
problems associated with comments getting out of date, and they can 
really provide some useful context for someone who isn't familiar with 
the code.

In my experience with f-spot the lack of contextual comments makes it a 
*lot* harder to start fiddling with the code.

Warren