|
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
|
|
|
|
|
Right On Target! ALL?
I comment all of these things, but not in all instances. For example, I don't comment the namespaces that are declared by the IDE, but I explain any others I add, and in particular, those that are my own (viz-a-viz standard namespaces).
My memory is not that good, or maybe I've too many things to remember after all of these years, but the hints as to "what and why" - even for stuff that's common - aren't painful, and when you have to look back into it on that imminent dark day ahead, you don't have to drive yourself mad looking at an entire application to understand the context.
Documentation occurs at three levels:
a) Each method will have a description of why it's there, and a running history of UPDATE's and FIXes. These are marked as such.
b) Most code will have comments, whether as a block or even line-by-line. A comment might not make sense at a context less than block-level.
c) A separate projname.ver file is created, which contains a history of development, modifications, and fixes. This is help for those times when you need to trace back to "what did I do around then, and since" when all this trouble started.
d) If I get crazy, I'll even sort the IDE-generated declarations into logical (rather than chronological) groups (e.g., by panel, then associate label to it's control. System Menu items sorted to reflect the actual menu structure).
Item (d) is, by the way, only for extreme cases - where that sorting will simplify what could become rather complex mantenance. I'm not that anal.
In general, there's a clear heirarchy: if it's part of the dev environment, and not my work, then it will probably not be commented. If I'm to blame, I want to have my excuses written in advance.
A bit idealistic, especially in these days of suddenly being outsourced, but I think that the people who sign my pay-checks deserve code that's as 100% easy-maintenance as possible.
"The difference between genius and stupidity is that genius has its limits." - Albert Einstein
|
|
|
|
|
This survey is rigged! Who can honestly argue that they comment EVERY single instance of a certain TYPE of entity? I thought there would be options like "variables without clearly obvious purpose" and so on. Honestly who cares what the type of construct it is that people comment. I'm more interested in when and why people comment things, not whether they're commenting a private static field or an abstract method... who cares?
|
|
|
|
|
.... you delve into another developer's code and find meaningful, considered commentary on the application logic which cuts in half the time you spend trawling through reams of underscores, esoteric naming conventions, and hastily-named methods, is the time you realise how important this is.
for me commenting is a religion. That's not to say I comment everything, but I certainly think it's worth my while to take a step back at the end of a piece of work and say, okay, what does this really do to the outside observer? Particularly with XML commenting, a great new feature in VS.Net and one of the things that makes it worthwhile to develop in, you should really NEVER be exposing an interface without at the least some kind of explanation as to what you can expect to get out of a function and what you need to put into it. Any less, IMHO, is just sloth of the worst order. Everybody wants get home at the end of the day with the maximum possible work done, and relax. But failure to comment just increases the burden for the guy coming after you, and makes you a sloppy coder.
The whole "My code is so good it doesn't need comments" argument is one I've heard many times, and it just doesn't wash. For one thing, in my own experience, the uncommented code is about 30% more likely to fail under unusual test conditions, because the developer was not the kind of person to assume the worst and code defensively. It's also almost always messier, so how can people expect that it's readable enough to not need commenting?
All the dude ever wanted... was his rug back.
|
|
|
|
|
I have a habit of doing what I call "comment driven coding"... I write the comments first, then fill in the code afterwards.
This works out well, because it keeps me initially focused on design and workflow, without getting bogged down by the nuts and bolts of implemntation. Also, this is good for projects that I'm working on with other people or when it's something that I need to leave and come back to for long periods of time.. When I first write the comments, I include a level of detail sufficient to allow me to walk away from the project and come back a month later and still be able to write it with the same amount of clarity and completeness as when I wrote the comments. This could be very high level, or very low level if I need to point out a important low-level detail that may not be obvious or standard.
This is not quite to the extreme of "literate programming" but similar in concept.
-Troy
|
|
|
|
|
illium wrote: I have a habit of doing what I call "comment driven coding"
Guilty as charged!
I have been known to do the same thing, it helps sort out the logic in my brain. I have been known to write the frame, so to speak, and fill the betweens ({ /*…*/ }) with comments regarding my logic. This helps and keeps you from forgetting the next step after doing some piece of complicated logic that drives the following steps out of your mind. I may not keep all those comments, but find them very useful during development.
INTP
"Program testing can be used to show the presence of bugs, but never to show their absence."Edsger Dijkstra
|
|
|
|
|
Religion, politics, football and commenting code...
This really is another one of those subjects that shouldn't be discussed amongst friends 
In truth I work for a guy that wants a comment above every single line of code. Now while I could almost see the point of this if we ran a pure ASM shop that turned over staff at a high rate, we aren't, we mostly use VB.NET and the youngest member of staff was 3 years old last month.
I'll admint to being guilty of hardly every putting comments into my code but I do use very descriptive object/function naming eg.
Public Function intCalculateAgeInYearsFromDateOfBirth(byval dtmDateOfBirth as datetime) as integer
How much more helpful would you find it to have 5-10 lines of comments which mostly boil down to "Look at me! I made this!" obscuring your view of the code?
It's at this point I'm going to stick my neck out and disagree with melchizidech. By no means am I tarring everyone with the same brush but I've found through personal experience that code littered with comments tends to be messy, poorly conceived, lacking in logic and far too often just plain wrong. I've seen far too many snippets along the lines of:
<br />
'This used to be boolean but we've had to change it to an integer after changes from above<br />
Dim blnTest as integer<br />
And for some reason people seem to think that commenting it makes it OK.
Argh!! Late for work now due to a desire to rant
d4m0cl3s
|
|
|
|
|
It depends what part of my post you're disagreeing with. I mean, you're taking extreme examples of the very worst kind of code commenting and using them as an argument against commenting in general. And from the point of view of usability/readability, don't you think having ridiculously long method names like the one above is almost as bad? The method name you've used there, is the InYears strictly necessary? I think most reasonable people would assume it was in years. And FromDateOfBirth? How else would you calculate an age?
OK, the reason I made those comments was to illustrate precisely what my point was - everybody has a different 'level of assumption' with regard to code. Some people will look at something and say 'that's obvious', some won't. You yourself, coming back to your code after a long hiatus, may struggle to remember what the hell you were doing. That's not poorly constructed code or bad doco, it's just the way the mind works. And the structure that you force on yourself, both in making things readable and logical, in commenting, is only ever a good thing. The examples you've referred to are of those who choose to be lazy about it - 'oh, i comment everything so that means I can write crap'... not so. And I'm not talking about every line of code either. Just that at the very least a method, unless it's completely trivial, should have some kind of description on it. You wouldn't build an electronic device without an instruction manual would you? Well why hand somebody a piece of software that doesn't say what it does?
All the dude ever wanted... was his rug back.
|
|
|
|
|
First of all, apologies for the long delay in responding. Sometimes things get a little too busy round here.
Anyway, I'll admit that I've never used that particular function name and yes I probably would used a far shorter (but just as readable) function name.
However, I still have to struggle on day after day sorting out *properly commented* code which had apparently passed a peer review and been put into a production environment. It's got to the stage where I've started removing comments because they're either misleading, wrong or point blank irrelevant. Commented code is good in theory but if the standard of the comments is better than the code itself you might as well bin the lot.
As for the instruction manual metaphor, that's more in keeping with a proper development spec rather than commenting. I'd consider comment s be more along the lines of the litle numbered tabs on an modelling kit. They can be useful but when you get to different parts with the same number, which should you use?
And finally, I'll apologise for the harsh tone of my original post, you'll understand when you get a manager that likes to put his name all over things.
|
|
|
|
|
"if the standard of the comments is better than the code itself you might as well bin the lot. "
I couldn't agree more. My point is not that commenting each and every line of code is not in and of itself productive. I would make the case though that establishing a rule that each logical part of a software component must be commented is both necessary and productive.
"As for the instruction manual metaphor, that's more in keeping with a proper development spec rather than commenting."
Fair point I suppose. But personally I prefer commenting at the code level because it then forms part of the delivered product, and lessens the need to refer back to a spec document all the time, which I think is cumbersome. Specs should be higher-level, describing the system in the large, referring to the "What" of the app, whereas comments I would like to see as the "how". I'm not too sure what you're going for there with the reference to different parts with the same number, I don't see how that relates to properly commenting code.
As to the "why"..... don't get me started...
And lastly of course, apology well and truly accepted.
All the dude ever wanted... was his rug back.
|
|
|
|
|
I ticked everything except the first and bottom two answers. I mainly develop in C# and use XML comments on all of those to gain/share the intellisense feedback with other developers. Once it is habit you don't even think about doing it. Some people don't bother to comment private methods (reflected in the results here), but IMO the time taken to make the distinction when declaring it is usually less than the time to hit three /// and start typing.
I would only have been able to tick the bottom answer if it said 'occasionally'. I only comment method logic when it is beneficial to someone to do so. Otherwise, what is the point?
|
|
|
|
|
I'm sort of like you David but not all the time. My approach is to document pretty much all public methods and properties. Then I document all non-trivial protected and private elements. Then we can produce developer-friendly NDoc or Sandcastle documentation for the code maintainer. But most people seem to have no concern for the maintainer. They're just interested in cutting code as quickly as possible.
David Wulff wrote: I only comment method logic when it is beneficial to someone to do so.
It's the "why" that may be important here rather than commenting the logic. Apart from that I sometimes insert section summary comments. These often serve as good hints for extracting those sections into their own routines, thus eliminating the comments.
Kevin
|
|
|
|
|
The survey is fundamentally flawed; all the options begin with "All". Since I don't comment ALL of anything I tried to vote with no options checked but my vote was not accepted.
The results cannot possibly be representative: they only represent the votes of people who comment ALL of something.
Phil
The opinions expressed in this post are not necessarily those of the author, especially if you find them impolite, inaccurate or inflammatory.
|
|
|
|
|
That's the point of the survey. Everybody sometimes comments this or sometimes comments that. I want to see who consistently and dilligently comments what.
cheers,
Chris Maunder
CodeProject.com : C++ MVP
|
|
|
|
|
Chris Maunder wrote: That's the point of the survey. Everybody sometimes comments this or sometimes comments that. I want to see who consistently and dilligently comments what.
But that's not very conclusive. How do you know how many people could not vote at all?
I didn't vote too, since I didn't find any option I could vote on 
|
|
|
|
|
Maybe this is a subtle way of saying you need to ensure your code is better commented 
cheers,
Chris Maunder
CodeProject.com : C++ MVP
|
|
|
|
|
HAHA. Or maybe it's a trap to see how many pinheads need to lighten up. 
Really, I'm rather proud that I can't answer. I'm not about to blindly waste my time throwing in comments on everything just so those comments can fall out of sync just as fast as someone can checkout a file and make changes.
I will comment structures and operations when their meaning is not obvious by looking. And I will comment what changes occurred to the code and why. But, other than that it's all self-documenting code. 
A severed foot is the ultimate stocking stuffer.
- Mitch Hedberg
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
