|
"If you can say it in code, do so. Otherwise, say it in a comment."
He made this statement in a C++ class I took from him. This comment made a profound change in how I documented my code. I used to comment everything, whether it really needed it or not. Now, my commenting is very context dependent. Header files I tend to comment fairly well, providing descriptions for methods and their arguments when they are private. Sources I comment whenever an algorithm is non-trivial, and to partition major pieces.
The end result is that my code is more concise, easier to read, and I'm more productive.
Software Zen: delete this;
|
|
|
|
|
I just finished a 2500 line C project. 20 Comment lines total. Why comment when code is readible?
Cheers
PS: one method comment is:
//if you wanna figure out whats going on here, set up a truth table
leppie::AllocCPArticle("Zee blog");
|
|
|
|
|
2500 lines? That's all? Small-timer.
"When a man sits with a pretty girl for an hour, it seems like a minute. But let him sit on a hot stove for a minute and it's longer than any hour. That's relativity." - Albert Einstein
|
|
|
|
|
Gary Wheeler wrote:
Sources I comment whenever an algorithm is non-trivial, and to partition major pieces.
OR whenever you use a library function/API tha thas a bug, and you have to do something contrary to the documentation (or the documentation has a bug) to get around it.
"When a man sits with a pretty girl for an hour, it seems like a minute. But let him sit on a hot stove for a minute and it's longer than any hour. That's relativity." - Albert Einstein
|
|
|
|
|
That's a case where the code can't 'say it' clearly; a comment is called for.
Software Zen: delete this;
|
|
|
|
|
When its good, its out of this world...
When its bad, its better than nothing...
Steven J. Ackerman, Consultant
ACS, Sarasota, FL
http://www.acscontrol.com
steve@acscontrol.com
sja@gte.net
|
|
|
|
|
And not having any makes you cranky?
Software Zen: delete this;
|
|
|
|
|
... and who will be maintaining it. If the purpose of the code is clear (e.g., you know it's a GUI app that does blah), then well-written code is better than comments.
However if it does something that someone maintaing the code might not easily understand (e.g., drivers, system code, or mathmatecal solvers), then comments are better, because if the reasons behind doing something aren't understood, then the best written code in the world won't help.
So I guess in summary: well-written code can say what is being done, but only comments can say why it is being done.
However more often than not, it's probably the "what" that's important.
"When a man sits with a pretty girl for an hour, it seems like a minute. But let him sit on a hot stove for a minute and it's longer than any hour. That's relativity." - Albert Einstein
|
|
|
|
|
I'm a big fan of comments and was going to vote for them, but I spoke to another developer here and changed my vote to prefer understandable code.
His point? The best commenting in the world is no use if it's not in a language you understand.
(In his previous job with a games company, as an English speaker, he had to work with code commented in Japanese.)
Gavin Greig
"Haw, you're no deid," girned Charon. "Get aff ma boat or ah'll report ye."
Matthew Fitt - The Hoose O Haivers: The Twelve Trauchles O Heracles.
|
|
|
|
|
Gavin Greig wrote:
His point? The best commenting in the world is no use if it's not in a language you understand.
You can say the same for code, though, too. I've seen code with variable names in Russian (and I'm not fluent in Russian, about all I know is "nyet". )
"When a man sits with a pretty girl for an hour, it seems like a minute. But let him sit on a hot stove for a minute and it's longer than any hour. That's relativity." - Albert Einstein
|
|
|
|
|
Navin wrote:
You can say the same for code, though, too. I've seen code with variable names in Russian
LOL
I once new a young programmer fluent in Russian that added all his comments etc in Russian as a joke.
When he died in a motor-bike accident the company employing him was really shagged.
Regardz
Colin J Davies
* WARNING * This could be addictive The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Code may have unhelpful variable names (and I guess names in a language you don't understand would fall into this category) but at least you have other clues as to what's going on - you may know whether the code works or doesn't, you can watch what it's doing, and you will be familiar with most of the syntax even if you can't read the variable names. With "easily understandable code" - primarily well laid out, if the human language isn't a common factor - this will be easier.
With foreign language comments, you don't have the same clues to help you out, so if you can only have one of easily understandable code or good comments, the easily understandable code wins.
I've worked with extremely horrible variable names in MUMPS (Massachussets General Hospital Utility Multi-Programming System, a programming language of horror) and while I would never want to go back, it is possible to make something of the gibberish so long as you have the syntax to help out.
Gavin Greig
"Haw, you're no deid," girned Charon. "Get aff ma boat or ah'll report ye."
Matthew Fitt - The Hoose O Haivers: The Twelve Trauchles O Heracles.
|
|
|
|
|
|
Not sure what the int is supposed to be
Matt Newman Sonork: 100:11179
"Whoa, that ruled! What function key do I gotta press to get that to happen again?" - Strong Bad
|
|
|
|
|
Nishant S wrote:
//remember to add code to check g_tot later //sorry - going out for coffee now/ so cannot do it
Oh man, I'm dying to put a comment like that in *my* code somewhere now, too.
<br />
"When a man sits with a pretty girl for an hour, it seems like a minute. But let him sit on a hot stove for a minute and it's longer than any hour. That's relativity." - Albert Einstein
|
|
|
|
|
How about this one:
<br />
"Sucks less" isn't progress - Kent Beck [^]
Awasu 1.1.1 [^]: A free RSS reader with support for Code Project.
|
|
|
|
|
OK, where's the :projectile-regurgitation: emoticon?
Oh well, I guess will have to do.
Software Zen: delete this;
|
|
|
|
|
..but at least if you have understandable code, people can put their own comments in.
Really, though, people put appallingly few comments in their code these days.
"Blessed are the peacemakers, for they shall be called sons of God." - Jesus
"You must be the change you wish to see in the world." - Mahatma Gandhi
|
|
|
|
|
Its like a silent rebellion from the incoming generation
Matt Newman Sonork: 100:11179
"Whoa, that ruled! What function key do I gotta press to get that to happen again?" - Strong Bad
|
|
|
|
|
I submit...
... code that is not commented cannot be easily understood.
|
|
|
|
|
I beg to differ.
Code can be written in such a way that comments aren't necessary for it to be easily understandable. Not always - but enough times that comments can be minimised.
Whether or not there is ever actually a case for minimising comments based on how neat the code is is debatable. Clearly having both comments and understandable code is ideal but I've been reading a lot of code lately that is either one or the other (unfortunately some of it is mine).
cheers,
Chris Maunder
|
|
|
|
|
While it is certainly true that good coding style and well-chosen names (to name just two techniques) help a lot in making code readable, it is also true that only mickey-mouse projects can be understood without comments, diagrams, and documentation.
Projects that take several man-years to develop and contain dozens of classes simply cannot be understood by good coding practise alone.
Documentation, model diagrams, and comments are paramount. The measure is not whether the author finds the code self-explainatory, it is whether a fellow developer can navigate and take over control eventually.
After all, when the more tedious maintenance work starts, you will want to move on to a new project, won't you
Bernd
|
|
|
|
|
Out-of-Date documentation can be worse than no-documentation at all. The problem I have found on previous projects is that the more detailed the code design documentation (ie. physical design), the more often a paper-based document will become obsolete.
I am finding XML Commenting and NDoc to be really useful for teaching developers to improve the commenting of their code, as well as being able to generate up-to-date documentation that stays current with the code.
|
|
|
|
|
Chris Beckett wrote:
Out-of-Date documentation can be worse than no-documentation at all.
Nothing worse than wrong directions.
leppie::AllocCPArticle("Zee blog");
|
|
|
|
|
Chris Beckett wrote:
Out-of-Date documentation can be worse than no-documentation at all.
I agree 100%. I see this a lot with open source projects.
John
|
|
|
|