|
Sander Rossel wrote: I'm so sick and tired of code comments that just sit there being useless (which is 99.999999% of all code comments I've come across)...
The other 0.000001% can save many hours, though.
I'm very sparing with comments but if it's something I've had a major battle and hours on Google to resolve, I'll always stick an explanation in.
Yes, we've all seen
//return
return;
at some point in our lives and marveled at the idiocy of it, but every now and again a well judged comment can save us a from a whole world of pain.
|
|
|
|
|
PeejayAdams wrote: but every now and again a well judged comment can save us a from a whole world of pain
I have yet to see such a comment 
|
|
|
|
|
Sander Rossel wrote: I have yet to see such a comment
You're yet to see my code
|
|
|
|
|
There are two options here:
Your code is so weird you have to constantly comment it...
Or your code is fine and you're just commenting the obvious.
Make your pick 
|
|
|
|
|
This did actually get me wondering how many inline comments I actually use. Looking through some open projects, it appears that I use far fewer than I'd have imagined but I certainly wouldn't remove any of those that are there. I always work on the basis that tomorrow I'll have forgotten something that I knew today.
I very much concur with Chris's comments about the 100%
|
|
|
|
|
The existence of one good comment does not justify the existence of the other 9,999,999 useless ones, though. By all means, add the good one, but for the love of the gods, skip the other wastes of space.
|
|
|
|
|
!00% agree that comments need to be meaningful.
However, I present my rebuttal as to why comments are necessary[^].
It's not about writing meaningful comments. It's about writing comments that are meaningful to everyone across time. The "but this is obvious" trap has caught us so many times that I had no choice but to insist on
a) method and parameter comments, even when "obvious".
b) inline comments on anything not blindingly obvious.
Sometimes you just have to write complicated code., and sometimes you have to write code that looks like it's totally unnecessary. Maybe you're optimising, maybe you're working around an issue that happens 1 in a thousand times and everytime you see the code you need reminding that it's there for a reason.
One comment I will make is that, 100% of the time, it's dangerous and outright wrong to make statements along the lines of "100% of the time".
cheers
Chris Maunder
|
|
|
|
|
Chris Maunder wrote: I present my rebuttal as to why comments are necessary[^].
You do make a good point. What's obvious to me now may not be obvious to others now and/or later or myself later. When you comment everything at least it will be clear to everyone always.
Except that commenting isn't easy and many programmers aren't very good at it.
A lot of comments I've read are just the name of a function, but properly spaced and capitalized. Or really state the obvious, like "assign the variable" (really, I've seen multiple programmers do it... why would anyone comment that?  ).
And comments are just lines of code that need to be updated, something you can't test for and which is easily, and often, forgotten.
In all the projects I've worked on so far I've learned to ignore comments because never ever ever have they actually helped me. Only when I'm really stuck and I see a comment somewhere do I read it, only to be disappointed once again.
A lot of comments I read aren't even true, they're downright lies and, if anything, confuse rather than help!
Worst case scenario, a comment makes good sense (a rare case indeed), but the code doesn't do what the comment says it does, now who's right?
I can remember a few times where I have commented code.
One was a timer that should trigger at 11:00, but triggered a few milliseconds early. Upon completion I got the next time at which it should run which was... 11:00! And it immediately triggered again. After days of debugging (where the problem never occurred) I found out the milliseconds were the problem. Fix and comment.
Another was with Crystal Reports where getting a property on an object caused the whole object to drop its state (the connection string was reset etc.) rendering it useless...
That's some of the weirdest sh*t I've seen, so that's when I wrote a comment.
Other than that I mostly remember deleting comments like "assign the variable", "Save the customer" (above the line customer.Save();), "Save the customer" (above the line product.Save();), "Helper variable" (above the line string helper;), etc... 
So if I have to pick between 95% useless comments that annoy me to no end and 5% comments that may be helpful someday or no comments at all I'd go for no comments at all. I'm pretty sure I can figure out that weird piece of code if ever the need be
You DO make a good point though and I can understand why you'd work that way.
|
|
|
|
|
I agree that the boiler plate code, CRUD and the blindingly obvious, does not need commenting.
However a complex piece of coding requires not just what you did but more importantly WHY you did it. The number of times I have sat there scratching my head wondering WhyTF I would write such an abomination, and THEN I read the comments and the memory kicks in. I may still shudder with despair but at least I know why.
I also comment in a URL to any tasty bit of code I have snaffled from the interwebs, let some other poor sod do the doco 
Never underestimate the power of human stupidity
RAH
|
|
|
|
|
/* This line has to come here for some reason for the system to startup... do not remove!!! */
"Program testing can be used to show the presence of bugs, but never to show their absence."
<< please vote!! >></div>
|
|
|
|
|
I don't expect people to write down comments too. I just make meaningful name to my variable and function.
|
|
|
|
|
So do your variable and function names explain "why" as well?
You have just been Sharapova'd.
|
|
|
|
|
yes, sometime have lengthy variable name because I am training to read code without comments like those in GitHub or StackOverflow
|
|
|
|
|
Generally I won't write comments too, with same reasons, but sometimes commenting is really necessary. I'm a simple developer, if necessary I write comment, if not, I don't. C'mon, who needs to write comment to a function whose name is Login? 
|
|
|
|
|
true right. I write comments for co-worker
|
|
|
|
|
[joke]
Beginner Luck wrote: I just make meaningful name to my variable and function
That's what I do as well. Here, enjoy this masterpiece.
public double ThisMethodCalculatesTheInsurancePremium(Insurance basically_All_That_We_Collect_On_Screen_Plus_Some_Flags_That_Are_Set_Based_On_User_Inputs_Oh_And_Totally_Forgot_Dynamic_Pricing_Flag_Works_Opposite_To_The_Way_It_Is_Named_I_Did_Not_Name_It_So_I_Will_Not_Change_It)
[/joke]
"You'd have to be a floating database guru clad in a white toga and ghandi level of sereneness to fix this goddamn clusterfuck.", BruceN[ ^]
|
|
|
|
|
and I include my current self and usually address "us" as "we need to..."
<sig notetoself="think of a better signature">
<first>Jim</first> <last>Meadors</last>
</sig>
|
|
|
|
|
Mandatory Geek and Poke: http://geek-and-poke.com/geekandpoke/2013/11/24/simply-explained[^]
I try to write good, usable comments during the initial writing of my code. Then, after I have worked on some other stuff for half a year before returning to make a new release, I add 50% more comments for the parts of my own code I do not immediately understand - and delete half of the old comments because they are really redundant. After two or three releases, with fewer and fewer additions/deletions of comments, those left are usually quite helpful.
|
|
|
|
|
Most of time, Managers and Team Leaders won't see your code, they just want to know it if works or not. But code efficiency and maintenance is the main aspect for long running projects, comments will always helpful in such cases.
Yes, debugger is there to trace to code but comments are more useful for elaboration of logic.
Find More .Net development tips at : .NET Tips
The only reason people get lost in thought is because it's unfamiliar territory.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
