Re: Comments in code

["George Fragos" <fragos gmail com>]

Lazy is the one I recognized as well.  Commenting code after the fact is never as effective as starting with the comments.  The comments then reflect the design and flow of modules and routines.  I always hated flow charts.  As part of the design process, I've always written comments  when the decisions were made as to what function goes where and how do they relate to each other.  When code is written some lower level comments are added as appropriate.  Meaningful labels for functions, variables and passed parameters are the finishing touch.  When the actual code impacted the design and purpose of another module that modules comments were updated, even if no code had yet been written for it.  We all have our own styles of problem definition which is after all an abstract thought process.  My approach developed over time, starting in 1964. -- George

On 12/29/06, Marcus Hast <marcushast gmail com> wrote:

Hi all,
This problem is something which I reacted against as well when I began
browsing the code. Fortunately the code is pretty easy to understand.
(But the MainWindow could use some comments to make it easier for
beginners to find their way around.)

As a person who works for a company developing and designing software
for a living there are a bunch of reasons why you shouldn't put in
comments and Stephane list quite a few of them. They are pretty much
all crap though, except for:

> - i'm a bit lazy

My personal experience is that the most important part is that each
method/class should have comments to describe just what it is that
code is supposed to do. Just like Stephane state it's possible for the
comments and code to go out of sync; but if you change the purpose of
a method or class you should change those comments to reflect this.

In this way it's also easier for you to find bugs when the code is
doing something funky. I found some pretty odd code in the source (for
the versioning) if I had a comment stating what that function was
trying to do then it would be easier for me to figure out if the code
was doing what it was supposed to. Otherwise I first have to try and
figure out what the code does, and then from that infer what the
actual goal of the code was.

However adding comments to all the code in the project would take
quite an effort. So I think a good way to handle it right now is to
encourage people to add comments to the code they check in.

Michael: I've spent some time going over the code in order to
implement some things for the project. I have a short vacation coming
up and I'm considering playing we the source a little during that
time. If you want to I can try to look over my notes on the project
and share that with you. It's nothing particularly insightful and it's
a bit limited as I've been looking at the parts of the code for the
main screen a bit as well as the code for the versioning system.

/Marcus
_______________________________________________
F-spot-list mailing list
F-spot-list gnome org
http://mail.gnome.org/mailman/listinfo/f-spot-list

-- 
Have a nice day -- George
____________
George Fragos
fragos gmail com
73 East Swift Ave.
Fresno CA 93704