|
"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
|
|
|
|
|
I think if you interviewed everyone who's bothered to answer so far, you'll find that almost none of them were aware that the poll is about the word "all" and has very little to do with the word "comment."
You should have at least added a final option of "There's nothing that I ALWAYS comment in my code" to give yourself a true comparative analysis, and to clarify the actual point of the poll.
Grim (aka Toby) MCDBA, MCSD, MCP+SB
SELECT * FROM users WHERE clue IS NOT NULL
GO
(0 row(s) affected)
|
|
|
|
|
you should have added a single other choice: "I never comment code". It would have emphasised the "All" choices and given those of us who write self-documenting code a way to vote.
Silence is the voice of complicity.
Strange women lying in ponds distributing swords is no basis for a system of government. -- monty python
Might I suggest that the universe was always the size of the cosmos. It is just that at one point the cosmos was the size of a marble. -- Colin Angus Mackay
|
|
|
|
|
I took all to mean 90% of the time . Guess it's too late to change my vote now . Well judging from everyone else's votes, I'm a bit slack at commenting.. but then I just don't see the point of commenting something that's already obvious. (Once I start commenting I spend half an hour just making sure it's understandable to a primary school student who's technical knowledge extends only as far as changing his phone's ringtone ). Maybe I need to find that elusive "middle road"...
"For fifty bucks I'd put my face in their soup and blow." - George Costanza CP article: SmartPager - a Flickr-style pager control with go-to-page popup layer.
|
|
|
|
|
Agreed as I could not truthfully vote for a single item.
John
|
|
|
|
|
I do most of my comments in Complicated Logics (Nested Loops, Comma Separating a string etc.,)...
Apart from that I thinks its necessary to comment All classes, structs and interfaces and Member Variables
Avoiding variables like i, j, k and naming them with proper variable names (something like nEmployeeID) reduces the need of comment in most of the places...
|
|
|
|
|
Yea, agree to this. I comment *where necessary*, not where a specific scheme forces me to comment (that often lead to comments of the form "function X does X" when X itself is descriptive enough). Therefore I mostly comment on the algorithms and on what the code does, not on static structures.
|
|
|
|
|
I agree with you guys, I comment only parts of code that i think is complex and easy to miss if i return to it later. What's the point in commenting every single line of your code - in fact, its a bug on its own.
laolusrael
|
|
|
|
|
I cut down the amount of comments to just the bare minimum. Only member variables and stuff that's not obvious. Otherwise it's too hard to find the code from within the mass of comments
|
|
|
|
|
int i;
i = 2;
i *= 4;
|
|
|
|
|
Joergen Sigvardsson wrote: i *= 4; // Multiply by 4
That should be:
i *= 4;
|
|
|
|
|
The long version would be:
The even longer version contains an essay about caching and all its consequences. The longest one includes a powerpoint animation of the CPU die transistors going on and off....
|
|
|
|
|
But what about methods? It drives me nuts when I see a routine with no comment, especially if that routine has a name like "HandleAction" that tells you nothing.
I find it so easy to get into the deadly "I understand it therefor it should be obvious to everyone else" trap.
cheers,
Chris Maunder
CodeProject.com : C++ MVP
|
|
|
|
|
A better solution is using meaningful names, then you may not need the comment at all
|
|
|
|
|
I agree. If the methods and variables have poignant names, comments become superfluous and that's one less thing to update if the code is changed.
IMO, excessive commenting probably means the code is either of questionable quality, or the developer has a hard-on for comments.
I find the best way to write comments, is to re-visit classes after a few weeks (once I've forgotten the thought processes behind it all) and read it from a virgin perspective. That way, I'm more likely to place comments where really needed. The trick is reading it from someone else's point of view.
"And when I have understanding of computers, I shall be the Supreme Being!"
|
|
|
|
|
mungflesh wrote: I find the best way to write comments, is to re-visit classes after a few weeks
I have been known to do the same thing and often try to anticipate the need. Nothing like reading your old code and saying “why did I do that?” to see a comment is (was) required.
INTP
"Program testing can be used to show the presence of bugs, but never to show their absence."Edsger Dijkstra
|
|
|
|
|
mungflesh wrote: IMO, excessive commenting probably means the code is either of questionable quality, or the developer has a hard-on for comments.
That's worth a 5
Grim (aka Toby) MCDBA, MCSD, MCP+SB
SELECT * FROM users WHERE clue IS NOT NULL
GO
(0 row(s) affected)
|
|
|
|
|
Chris Maunder wrote: It drives me nuts when I see a routine with no comment, especially if that routine has a name like "HandleAction" that tells you nothing.
Ditto! It's also amazingly common to have wishy-washy names such as HandleAction. It can be OK when we're being very generic, e.g., in some kind of framework. but more often than not it's because the dev can't be arsed to think up a better name.
Kevin
|
|
|
|