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 <[EMAIL PROTECTED]> 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 [email protected] http://mail.gnome.org/mailman/listinfo/f-spot-list
-- Have a nice day -- George ____________ George Fragos [EMAIL PROTECTED] 73 East Swift Ave. Fresno CA 93704
_______________________________________________ F-spot-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/f-spot-list
