Re: Comments in code

["Marcus Hast" <marcushast gmail com>]

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