|
in reply to The art of comments: (rave from the grave)
I don't think "what is a good comment" is a good question. Comments seen in isolation mean nothing. Comments reflect code, and how one should use comments always depend on the code that's being commented. I think that the better the program is, the less comments it needs. A perfect program needs no comments at all. |
Re^2: The art of comments: (rave from the grave)
by BrowserUk (Patriarch) on Jul 07, 2005 at 11:28 UTC
|
Comments reflect code, and how one should use comments always depend on the code that's being commented.
Which is exactly why I didn't ask "What is a good comment", but "Please point to an example or two of what you consider to be well commented code".
Unfortunately, noone has yet responded to that request.
There *must* be some well commented code out there somewhere surely?
Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
Lingua non convalesco, consenesco et abolesco. -- Rule 1 has a caveat! -- Who broke the cabal?
"Science is about questioning the status quo. Questioning authority".
The "good enough" maybe good enough for the now, and perfection maybe unobtainable, but that should not preclude us from striving for perfection, when time, circumstance or desire allow.
| [reply] |
Re^2: The art of comments: (rave from the grave)
by polettix (Vicar) on Jul 07, 2005 at 16:56 UTC
|
A perfect program needs no comments at all.
I disagree on this. Readability should be one of the main target of a perfect program, and comments are an important part of it. Good comments let you better understand the main blocks, the purpose of the different functions (even "private" methods, whose commenting is useful to let someone hack on it) and basically leave the possibility to modify the code. To add new features, of course, because it's perfect.
Flavio
perl -ple'$_=reverse' <<<ti.xittelop@oivalf
Don't fool yourself.
| [reply] |
|
|
A perfect program needs no comments at all.
I disagree on this. Readability should be one of the main target of a perfect program, and comments are an important part of it.
I think the point is that a "perfect program" is so inherently clear that comments are unnecessary. Of course, there's no such thing, but the point is that, in the opinion of some, comments are often (ab)used as a substitute for clear programming.
| [reply] |
|
|
| [reply]
[d/l] |
Re^2: The art of comments: (rave from the grave)
by Anonymous Monk on Jul 11, 2005 at 22:14 UTC
|
How does the code, by itself, describe the reason why the code was written that way?
How does the code, by itself, describe the business needs that that section of code is supposed to fulfill? How does the maintenance programmer tell if those business needs have changed?
How do I use a programming language, in and of itself, to signal that a given, efficient but obscure algorithm is correct, and that the "obvious solution" is not the right one?
As a real world example, one of my friends worked on an open source game. He was repeatedly annoyed by people trying to "simplify" a complex section of code, by consistantly making simplifying assumptions that initially appeared correct, but simply weren't true for all cases.
How did he fix the code? He put in three formal proofs of algorithm correctness, documented the underlying assumptions that the would-be optimizers consistantly missed; and carefully listed all the criteria that a refactored solution would require in order to be complete.
People stopped breaking the code after that; because there was enough information in the comments to force them to realize what the code actually did, and why it needed to be written the way it was... | [reply] |
|
|
How does the code, by itself, describe the reason why the code was written that way?
Lots of ways. Good naming of files/instances/classes/variables. Good well structured acceptance/unit test suites. Good well factored code.
How does the code, by itself, describe the business needs that that section of code is supposed to fulfill?
Acceptance tests are one way. Good well structured, well named code is another.
How does the maintenance programmer tell if those business needs have changed?
How do comments help here?
How do I use a programming language, in and of itself, to signal that a given, efficient but obscure algorithm is correct, and that the "obvious solution" is not the right one?
Have a test suite that fails for the obvious, but wrong, solution? Make the complex code easier to understand so that the traps are easier to spot?
Okay, I admit it, I'm playing devil's advocate a bit. But only a little bit. Comments are not always a bad thing - especially if you lack a decent test suite.
However, there is a very bad tendency for people to use comments as the weapon of first resort when tricky code is encountered. Something isn't obvious - just add a comment.
A much better attitude in my opinion is to use comments as a last resort. Before that I will spend time trying to make the code clearer, separate responsibilities better, add explanatory tests, etc.
| [reply] |
|
|
