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 <[EMAIL PROTECTED]> 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 > [email protected] > http://mail.gnome.org/mailman/listinfo/f-spot-list > -- Luke Hoersten http://www.cs.purdue.edu/~lhoerste/ http://www.openradix.org/ _______________________________________________ F-spot-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/f-spot-list
