Quoting Lloyd Bryant <[EMAIL PROTECTED]> from ml.softs.gtk-gnutella.devel: :I'll have to remember that. I keep bouncing from one extreme to the other :in that regard - professionally, I tend to add TONS of comments, as most :shops I've worked at required such, while in the OSS arena I keep getting :messages to "not clutter up the code with unneeded comments". I guess it's :a matter of the project style....
Too many comments is just as bad as no comments: if there are too much text to read, chances are that that text will not be kept in sync with the code. Just put as many comments that you feel comfortable with and that you'd like to find in someone else's code. Usually, I'm verbose when I change code that I did not write, and I tend to be more terse with code I write: I put a high-level description of what is going on, and then tactical comments to explain what's going on. In any case, all new routines must have a leading comment explaining what they do in plain English. And all static variables should be documented at the place where they are declared. Oh, I write tactical and strategical comments BEFOPRE I code. I find that it helps me get my thought straight. If I can't express what I want to do in plain words, there's little chance I can code it correctly anyway. When the comment is written and I like it, I find that code follows naturally. A famous French writer once said: "Ce qui se concoit bien s'enonce clairement, et les mots pour le dire viennent aisement.", which translated would be: "What's well thought out will be clearly laid out, and words to say it will easily come out" (wording to keep the rhyme). Raphael ------------------------------------------------------------------------- Using Tomcat but need to do more? Need to support web services, security? Get stuff done quickly with pre-integrated technology to make your job easier Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642 _______________________________________________ Gtk-gnutella-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/gtk-gnutella-devel
