Re: Comments in code

["Luke Hoersten" <luke hoersten gmail com>]

I completely agree with high-level commenting. I hack on Banshee and
the methods and classes are all very well named except to understand
the flow you still spend a lot of time tracing through. It would save
a ton of time to simply read "this class is for this" and "this method
does this." This holds true especially for exceptional cases and lets
be honest, there are *always* exceptional cases.

Though I suppose it's not really a debate, more just personal
preference, I still like to give my two cents =).

-Luke

On 1/2/07, Warren Baird <photogeekmtl gmail com> wrote:
> 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
> _______________________________________________
> F-spot-list mailing list
> F-spot-list gnome org
> http://mail.gnome.org/mailman/listinfo/f-spot-list


--
Luke Hoersten
http://www.cs.purdue.edu/~lhoerste/
http://www.openradix.org/