|
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
|
|
|
|
|
You hit the nail on the head when a “fellow developer can navigate and take over control”.
For those of us who have worked on projects with several developers, the true test of ‘understandability’ is when another programmer can easily take up where you left off.
I personally prefer good coding with just enough concise commenting to alleviate the question: What was he thinking?!?
Wade
|
|
|
|
|
I agree. The only place I've seen lately where comments are mandatory regardless of the 'readability' of the underlying code is in assembly language. I'm maintaining an OS/2 device driver (don't ask; it isn't pretty) that is ~18,000 lines of assembly language. The source is probably 65% comments. It's just not possible to maintain this thing without verbose, inline documentation.
Software Zen: delete this;
|
|
|
|
|
Our assembly system is setup with a 6100 line limit. 
The first thing to go is comments. A typical line might get some inititals and a date to let me know who made a change and when, with a 1 line(71 char.) comment at the top stating what their change was about. The rest is mostly walking through by hand.
It sucks!
"Manifest plainness, embrace simplicity,
reduce selfishness, have few desires."
-- Lao Tzu BW
|
|
|
|
|
Have you considered writing a preprocessor for your assembly system that would strip comments out?
Software Zen: delete this;
|
|
|
|
|
I've thought about it, but I'm not handling the code for our editor anymore. I seem to remember hearing complaints that line numbers wouldn't match, or some other lame thing.
"Manifest plainness, embrace simplicity,
reduce selfishness, have few desires."
-- Lao Tzu BW
|
|
|
|
|
Jim A. Johnson wrote:
code that is not commented cannot be easily understood.
Well if you embed all comments within variable names it is 
Matt Newman
Sonork: 100:11179
"Whoa, that ruled! What function key do I gotta press to get that to happen again?" - Strong Bad
|
|
|
|
|
'nuff said 
God, I pity me! - Phoncible P. Bone
If I end up Windows ME someone is going to be hurting. - One of the answers to a question for What OS are you
|
|
|
|
|
...to get awfully unfunny if all 400k CPians want their shot at the CListCtrl joke 
Paul Watson
Bluegrass
Cape Town, South Africa
Crikey! ain't life grand?
|
|
|
|
|
I doubt that all 400k would get the joke.....the number's closer to bout a hundred or so.
But still, I'm glad I took my shot before it's passe.
God, I pity me! - Phoncible P. Bone
If I end up Windows ME someone is going to be hurting. - One of the answers to a question for What OS are you
|
|
|
|
|
...obviously have not been reading the text answers if you think it is only a 100 of us. As Chris will attest, ClstCtrl is hotter than Britney Spears and Madonna and becoming just as annoying
Nick Seng wrote:
passe
At first I thought "passe? keh?", thought you meant "passed". Then I realised that word rests on the use of the accented e.
Paul Watson
Bluegrass
Cape Town, South Africa
Crikey! ain't life grand?
|
|
|
|
|
....most of the people who voted for CListCtrl were serious. I was joking( well, mostly)
I didn't know how to accent the 'e'.
God, I pity me! - Phoncible P. Bone
If I end up Windows ME someone is going to be hurting. - One of the answers to a question for What OS are you
|
|
|
|
|
Nick Seng wrote:
didn't know how to accent the 'e'
alt + (numpad) 138 if you dont have the `-key on your keyboard. è
“Our solar system is Jupiter and a bunch of junk” - Charley Lineweaver 2002
|
|
|
|
|
alt + 130 (é) will fit better
Every gun that is made, every warship launched, every rocket fired, signifies in the final sense a theft from those who hunger and are not fed, those who are cold and are not clothed - Dwight D. Eisenhower
|
|
|
|
|
Doesn't bother me in the slightest, I had my turn at it in a previous survey
Maybe I'll put in <asp:repeater> the next one
--
Ian Darling
If I was any more loopy, I'd be infinite.
|
|
|
|
|
I hear Chris is working on an automatic membership cancellation gizmo for when people enter CListCtrl...
Software Zen: delete this;
|
|
|
|
|
|
Bah, who needs comments!;P
And by the polls, most people agree with me
God, I pity me! - Phoncible P. Bone
If I end up Windows ME someone is going to be hurting. - One of the answers to a question for What OS are you
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
