|
1. I name my methods carefully but always add method comments to ensure no ambiguity and misunderstanding of the name (Does "persist" or "store" mean the same thing? Depends...). This also provide a nice intellisense experience
-> I comment for others in my team
2. I comment gnarly code that I can't (or let's face it, don't have time to) rewrite properly. Maybe it's non-obvious, maybe it's temporary, maybe it's because there's a bug in the framework we're using that needs an odd workaround
-> I comment for those reviewing / maintaining the code / my future self who will need to fix it.
3. For code I'm making public I add comments to help newbies walk through it. It's educational code, not lean-and-mean code that needs to save every byte of comment space it can (is this even a thing?)
-> I comment for those looking to use my code
4. Sometimes I comment an exhausting / annoying piece of code with a snarky and what seemed humourous-at-the-time comment.
-> To future palaeontologists who stumble across my code. I hope it makes them grin.
cheers
Chris Maunder
|
|
|
|
|
While looking on the aspect of Leads and Managers, A good code will surely have comments with them not only for their recognition but also for the future newbies who place their hands on the code.
As well as of direct use to any programmer reading the source code, comments are sometimes processed in various ways to generate documentation external to the source code itself by documentation generators, or used for integration with source code management systems and other kinds of external programming tools.
The flexibility provided by comments allows for a wide degree of variability, but formal conventions for their use are commonly part of programming style guides.
Too much comments is also not encouraged.
modified 1-Aug-16 9:10am.
|
|
|
|
|
Real Programmers don't comment their code. If it was hard to write, it should be hard to understand. 
|
|
|
|
|
RJ_Zed wrote: A good code will surely have comments with them not only for their recognition but also for the future newbies
Newbies will not be working with my code, so in my world, your argument doesn't pan out.
In my world, good code doesn't "need" comments.
|
|
|
|
|
Slacker007 wrote: In my world, good code doesn't "need" comments.
Sometimes it's not the code that requires explanation but some quirk of the business logic behind it.
|
|
|
|
|
|
In that case, you need comments right?
|
|
|
|
|
Our shop documents the business process outside the code base about 99.9% of the time, and this is for the complex business processes. We don't use our code base to document code.
Besides, you are not allowed to even look at our code, until you have read the business docs, design docs, etc., and understand the overall system.
So, we use comments in code....about .1% of the time....and it is not a "need".
|
|
|
|
|
The robot overlords are presumably bright enough to understand my code even without comments, and by the time the paleontologists take an interest in me or my code, I expect to have been long retired.
If you have an important point to make, don't try to be subtle or clever. Use a pile driver. Hit the point once. Then come back and hit it again. Then hit it a third time - a tremendous whack.
--Winston Churchill
|
|
|
|
|
Do robot overlords have a sense of humour? I sincerely hope so...
We're philosophical about power outages here. A.C. come, A.C. go.
|
|
|
|
|
Who do you write comments for? really? Is this noob hour?
|
|
|
|
|
Slacker007 wrote: Is this noob hour?
Judging from the comments I've read over the past six years, no, it's not noob hour, it's a noob age...
|
|
|
|
|
One thing I love about polls is that you start with an expectation of what the answer is and watch as you're proven wrong.
Open your mind a little to the possibility that what you feel is self-evident may, in fact, be not.
(And while you're at it you can put your money where your mouth is[^]  )
cheers
Chris Maunder
|
|
|
|
|
|
Apparently, you don't have knowledge about research and polls. Information you don't care is valuable for researchers. I didn't know that until I've worked for a research company, you'd be surprised the statistics they generate from simple answers... 
|
|
|
|
|
In earlier time comments were written to enhance the LOC counter.
//TODO: check when this was modern 
Press F1 for help or google it.
Greetings from Germany
|
|
|
|
|
Just like some of the formatting rules requiring even rather simple statements such as
if (x<0) y=0;
using brackets on their own separate lines and a blank line after it:
if (x < 0)
{
y = 0;
}
<blank line>
That increases your productivity by a factor of five!
|
|
|
|
|
Quote: Who do you write comments for?
To guide ego-ed person like you. . Adding on top what other said, You really need comments when a logic is complex one writing a code only won't help.
|
|
|
|
|
By default, code commenting is off.
Whenever I write a piece of WTF code I first rewrite it. If that's not possible I might comment.
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)...
I've said enough about that in my time here on CP though[^] 
|
|
|
|
|
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.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
