[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-devel
Subject:    Re: comment style
From:       "Aaron J. Seigo" <aseigo () olympusproject ! org>
Date:       2002-08-01 0:12:18
[Download RAW message or body]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Wednesday 31 July 2002 04:57, Henry Miller wrote:
> Perhaps I should put it this way: if/when I submit a patch should I put
> excess comments in it?   Is there a prefered way to document code that
> I'm missing?  Or is the belief in self-documenting code so strong that
> comments are discouraged?

i've found that commenting is about as personal as indent preferences =)

IMO commenting headers is very, very good, but i personally don't put many 
comments in the actual implementation when i consider it to be "obvious" code 
because:

 o when code gets changed, the comments often don't. this leads to misleading 
comments given enough time
 o i'd rather write code that is easy to understand than document hard to 
understand code with easy to understand comments[1]
 o i'd rather write code ;-)
 o if someone (including me) is going to modify the code,  i'd rather it was 
done based on an understanding of the code rather than an understanding of 
the comments
 o not everyone is an english speaker anyways[2]
 o i'm a lazy bastard who reads code quickly so comments don't buy me much [3]

i do, however, usually comment when:

 o the code is particularly strange
 o the code is an important bugfix
 o the code is non obvious
 o the code needs future attention
 o i've done something particularly clever[4]
 o i have a particularly poignant thought i'd like to share via CVS[5]

[1] the structure of that sentence should help explain why you probably don't 
want me commenting too much in the first place.
[2] isn't that a great cop-out? ;-)
[3] since i have to read the comments then read the code anyways
[4] i don't think that one has happened yet
[5] such as "the proof is simple, but the margins aren't big enough to 
document it completely"

- -- 
Aaron J. Seigo
GPG Fingerprint: 8B8B 2209 0C6F 7C47 B1EA  EE75 D6B7 2EB1 A7F1 DB43

"Everything should be made as simple as possible, but not simpler"
    - Albert Einstein
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.7 (GNU/Linux)

iD8DBQE9SHzj1rcusafx20MRAuhEAKCkMcsMEsXoN3veHbLLG6hl1fnGmwCbBv5d
ZwVsUIiZY/S59zBgU8IubUg=
=xRx5
-----END PGP SIGNATURE-----

 
>> Visit http://mail.kde.org/mailman/listinfo/kde-devel#unsub to unsubscribe <<
[prev in list] [next in list] [prev in thread] [next in thread]