|
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
|
|
|
|
|
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!"
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
