|
I have worked as a contractor for many years. I FIRMLY believe in comments to the point of being verbose. In most contracts where I am modifying code I find little, if any comments. In teams I have worked in, I am most always the only one commenting my code. IMHO, the poll does not represent the majority of coders whom, in my experience, do not comment at all.
|
|
|
|
|
Of course the problem with comments is that they have to be maintained in parallel with the code that's being maintained.
If the comments are mirroring what the code is doing versus what is 'intended', then there's the possibility (high) that the code will be changed (edited and or otherwise extended) beyond the scope of the matching comment - therefore misleading any future editor.
Hence, many times, if I'm having to debug and or extend functionality not written by yours truly, I'll strip out all of the comments so they don't distract (or otherwise deliberately mislead) me from the task at hand.
|
|
|
|
|
 In which situation we use Interface, Abstract and Inheritance.
Sathyanarayanan.N,
Photon Infotech Private Limited,
No. 2/102, Photon Towers,
Old Mahabalipuram Road,
Karapakkam,
Chennai - 600096.
Tamil Nadu, India.
Phone: +91 44 - 2450 1570
Mobile: +91 98843 67652
|
|
|
|
|
I call that an Oops moment.
Interface => Separates the implementation from the interface, useful in cases where you need the implementation to be interchangable.
Abstract => Sometimes you just don't want a class to be instantiated directly, such as the base class for a validator. you want users to instantiate specific validators, such as RequiredValidator, but not the Validator class itself as that one does nothing.
Inheritance => Ever build constructions like Person :: Manager? Also this is necessary for the Validator scenario, described above.
WM.
What about weapons of mass-construction?
"What? Its an Apple MacBook Pro. They are sexy!" - Paul Watson
|
|
|
|
|
In case you don't know "GhostDoc [^]" - A must have for C# programmers. (Free add-in for Visual Studio .NET)
|
|
|
|
|
Commenting is for little girls.
Puhlease, next you'll ask whether or not I unit test!
Did anyone bother Picasso with "Hey Pablo, what's up with that paint stroke - did you document it"?
Do you think Bach had time to unit test "The Goldberg Variations"?
Of course not! Real Programmers need none of these inhibiting bonds that ties us down and make us mere slaves and chattel of The Man!
Real Programmers need none of these things! Code written by Real Programmers is both self documenting and verifiably so superior to anything else that no testing is necessary!
¡El diablo está en mis pantalones! ¡Mire, mire!
Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)!
SELECT * FROM User WHERE Clue > 0
0 rows returned
Save an Orange - Use the VCF!
VCF Blog
|
|
|
|
|
Yeah me to , it compiled so $&"£ing release it thats what I say . I said it when the other team members on the mars probe said 'shouldn't that be in metric' and I say it now
|
|
|
|
|
a repost, but a goody, to match yours :-
Top 20 things likely to be overheard if you had a Klingon Programmer:
1) Defensive programming? Never! Klingon programs are always on the offense. Yes, offensive programming is what we do best.
2) Specifications are for the weak and timid!
3) This machine is GAGH! I need dual Pentium processors if I am to do battle with this code!
4) You cannot really appreciate Dilbert unless you've read it in the original Klingon.
5) Indentation?! - I will show you how to indent when I indent your skull!
6) What is this talk of 'release'? Klingons do not make software 'releases'. Our software 'escapes' leaving a bloody trail of designers and quality assurance people in its wake.
7) Klingon function calls do not have 'parameters' - they have 'arguments' -- and they ALWAYS WIN THEM.
8) Debugging? Klingons do not debug. Our software does not coddle the weak. Bugs are good for building character in the user.
9) I have challenged the entire ISO-9000 quality assurance team to a Bat-Leth contest on the holodeck. They will not concern us again.
10) A TRUE Klingon Warrior does not comment his code!
11) By filing this bug report you have challenged the honor of my family. Prepare to die!
12) You question the worthiness of my code? I should kill you where you stand!
13) Our users will know fear and cower before our software! Ship it! Ship it and let them flee like the dogs they are!
14) Our competitors are without honor!
15) Python? That is for children. A Klingon Warrior uses only machine code, keyed in on the front panel switches in raw binary.
16) Klingon programs don't do accountancy. For that, you need a Ferengi.
17) Klingon multitasking systems do not support "time-sharing". When a Klingon program wants to run, it challenges the scheduler in hand-to-hand combat and owns the machine.
18) Perhaps it IS a good day to die! I say we ship it!
19) My program has just dumped Stova Core!
20) Behold, the keyboard of Kalis! The greatest Klingon code warrior that ever lived!
(from http://gradha.sdf-eu.org/textos/klingon_programmer.en.html[^])
|
|
|
|
|
Forum-Leaders' comments notwithstanding, I think we need to open up the server generation to some discussion.
Quite often, and it seems more-and-more often, the survey questions pigeon-hole the respondant's too tightly. They request boolean responses to questions that (at least) seem to fit better into the "On a scale from one to ten" schema.
Now don't get me wrong - I enjoy the surveys, and the comments they generate. Why, it may even be that the style used is to encourage a second stream of thought spiced with a discontent of the survey's syntax . . . but I don't know that to be the intended effect.
Funny how whiny I've been, today. Weather's been beautiful and I feel just fine.
Just ignore me.
"The difference between genius and stupidity is that genius has its limits." - Albert Einstein
|
|
|
|
|
Hi Balboos,
Balboos wrote: the survey questions pigeon-hole the respondant's too tightly.
I agree - I wanted to vote on the survey, 'I comment ...'. In my case, I generally don't comment anything. However, I got a message "you have not voted".
Don't mistake not commenting for not documenting - I'll write a 30 page article explaining what I did and why 
Jeff
|
|
|
|
|
Per this post[^] - code is only self documenting to those who can read the code...it is worth throwing in the intent in comments so that this can be verified by anyone who is an expert in the problem space but is not a programmer. (After all you are as likely to misunderstand the problem space as you are to miscode the solution - perhaps more so)
-- modified at 11:02 Tuesday 29th May, 2007
|
|
|
|
|
I think that fits in well with my post below. Comments should never duplicate what the code is saying.
Comments always useful for answering 'why?' questions.
When the code has effects outside the immediate scope, comments should answer 'where?' questions. These answers are in terms of the effects of the code on its environment. The environment can be the user, the operating system, a file or data base, or anything else that it is manipulating.
If you are implementing an unusual or esoteric algorithm, they can answer 'how?' questions. There are plenty of algorithms out there for which the algorithm statement is relatively simple, but the code corresponding to it is complex.
The answer to 'what?' questions, should be the code itself.
Software Zen: delete this;
|
|
|
|
|
Duncan Edwards Jones wrote: The myth of self documenting code
I have a programmer here that still believes in self-documenting code. Even though only two weeks ago *I* had to tell him what *HIS* code was doing. He forgot. He claims that proves self-documenting code works, I say it proves it does not work. The fact that I still remember the intimate functionality (generally) allows me to pick up the specifics, but without a general idea of what does what and additional intimate knowledge of the data feeding his routines from the customer, I was able to figure out the code. Without that knowledge, no one could figure out what the heck was going on in that code.
However, it is a loosing battle, there is still constant battle over the ideas that "comments will not be updated and then misleading, but code is always current."  It's like saying, "because I won't do the work anyhow, I will make sure the problem is much worse if you force me to do this."
[just to clarify] I am not talking about abuntantly commenting, this issue is over absolutely never commenting anything, anywhere, ever, which is the stance this one programmer is taking. Code only, Zero comments, no why's, no where's, no nothing, supposedly code says it all.
_________________________
Asu no koto o ieba, tenjo de nezumi ga warau.
Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
|
|
|
|
|
... and there are many instances where comments are even useful to a *programmer*.
I'm a fairly proficient developer in a number of different languages. But if I'm in a given mindspace in order to work in a particular language, and I have to interface with services in other languages, I could easily (and often) misinterpret what the external code is doing, especially at crunchtime when I can least afford to waste time.
Afterall, even something as simple as the equalsign means markedly different things in different languages.
if (x = y)
in VB means something completely different than it does in most other languages. And while you could argue that such a line would technically be poorly written if it were in anything other than VB, the end result is that if I was trying to decipher it while I was in the mindset of programming in VB, I would completely misinterpret the purpose of the entire function containing that line and would not receive the result from the service I was expecting.
Whereas a simple comment stating "compares x and y, and returns splat if equal" - 2 minutes of time spent max - would potentially save hours of troubleshooting for other consumers.
|
|
|
|
|
Re: the code/comment synchronisation problem (which can never be completely eliminated) the approach to adopt is that comments should be as few as possible but as many as necessary. Many comments can be eliminated as a result of refactoring. For example, commenting of conditional expressions can be eliminated by replacing the expression with a readable Boolean variable.
The most important comments are (as you indicate) intent comments. In languages which support Design by Contract, many of these can be made self-documenting too.
Kevin
|
|
|
|
|
In a programming class he taught where I work, Dan Saks (former Secretary for the ANSI/ISO C++ Standard Committee) said the following:
If you can say it in code, say it in code.
Otherwise, say it in a comment.
In other words, your code should be as self-describing as possible. Where self-description fails, then you must comment.
Software Zen: delete this;
|
|
|
|
|
He totally right, so if I hat to read a lot of comments I got worried. 
Greetings from Germany
|
|
|
|
|
I totally agree. Overuse of comments can make code UNREADABLE. For example, the following comment is, IMO, completely redundant and useless:
// iterate the items list and set each item to read:
foreach ( Item i in items )
i.Read = true;
...whereas something like this could be very useful:
// this must be done before the call to RegisterItems, otherwise the ReadCount property will be incorrect:
foreach ( Item i in items )
i.Read = true;
RegisterItems( items );
...for example. That is, one should only document those things that are not immediately clear from the code. If you can't read code, you probably shouldn't be reading the comments either. 
|
|
|
|
|
Your totally right.
In your exmple I would check the Readcount for sanity
"you never know" && Moore's law
Greetings from Germany
|
|
|
|
|
I've heard Dan Saks' quote paraphrased as:
Code tells you what you're doing, comments tell you why.
Your example illustrates it perfectly...
|
|
|
|
|
Paul Glaubitz wrote: Code tells you what you're doing, comments tell you why.
1. Code tells you what your program is doing.
2. Comments tell you what the program is supposed to do.
3. The two are not necessarily the same.
|
|
|
|
|
Gary Wheeler wrote: If you can say it in code, say it in code.
Otherwise, say it in a comment.
My code says everything I want / care to say, that's why there is almost no comment.
|
|
|
|
|
With that attitude in mind; I would not want to have to modify any of your code.
|
|
|
|
|
I dont comment "all", this is a bad poll. 
I comment think when it gets tricky or I do somethings which arent obvious or got hacky.
At first sting I love writing "speaking code" in which the names of all says what is happing.
while( DoStuff() )
Display( "Please wait" );
Greetings from Germany
|
|
|
|
|
What's with this "all" business? Oh sure, Mr. Maunder writes:
Everybody sometimes comments this or sometimes comments that. I want to see who consistently and dilligently comments what.
So it's "all", as in "all the King's horses and all the King's men", is it? Well think about it. That's pretty much an impossible number of horses and men to reckon with.
Oh well, another survey relegated to the realm of fairy tale coding practices. 
Marc
Thyme In The CountryInteracxPeople are just notoriously impossible. --DavidCrow
There's NO excuse for not commenting your code. -- John Simmons / outlaw programmer
People who say that they will refactor their code later to make it "good" don't understand refactoring, nor the art and craft of programming. -- Josh Smith
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
