|
Seasoned programmers know well that code is the ultimate comment. When code reads like a story, there's hardly any comment needed. Comments come handy only when you have to break the flow of the story due to limitations of the language or adopt a complex hack to improve performance, etc.
|
|
|
|
|
I've seen some linq examples here that does NOT read like a story and definitely needs commenting
Never underestimate the power of human stupidity
RAH
|
|
|
|
|
I agree with you and I have seen simple structures like for loops that require comments. Any programming feature or paradigm can be abused if its purpose is not fully understood by the developer.
|
|
|
|
|
Comments are for business logic. There are often things we are told to do that seem crazy, but they are just the crazy things we're asked to do. So often times, the comments explain why I'm doing something I don't think makes sense to do.
Hogan
|
|
|
|
|
// I'm sorry
|
|
|
|
|
so I use long and explaining coding conventions and names and a clean control flow to make it easy readable.
Only when it gets wired I use comments.
This is working fine for me for some years. I understand my 10 year old code. (I hope so)
Press F1 for help or google it.
Greetings from Germany
|
|
|
|
|
To the poor souls who have to review my code
|
|
|
|
|
I do not fear of failure. I fear of giving up out of frustration.
|
|
|
|
|
Developers who have spent any time on large projects understand the importance of code comments. When you’re building many features into the same application, things tend to get complicated. There are so many data bits including functions, variable references, return values, parameters… how are you expected to keep up?
It should come as no surprise that commenting your code is essential, both solo and team projects.
Regards,
Palash
|
|
|
|
|
That's not what comments are for... That's actual documentation.
Comments are for those times you can't express yourself very well in the code itself: it says why you did something a certain way, for example.
|
|
|
|
|
Agreed. Documenting every bit of the code is more useful than cryptic, embedded comments. We're not obliged to read the manual but if it has been well written it should explain everything.
How often I fall victim to the copy/paste merchant who forgets to modify his comment for the new scenario.
We're philosophical about power outages here. A.C. come, A.C. go.
|
|
|
|
|
Palash Mondal_ wrote: how are you expected to keep up?
Design and implementation documents? Yes a radical idea which has not gained sufficient traction in all quarters.
Peter Wasser
"The whole problem with the world is that fools and fanatics are always so certain of themselves, and wiser people so full of doubts." - Bertrand Russell
|
|
|
|
|
I had to. I just had to.
Jeremy Falcon
|
|
|
|
|
That isn't complete without bacon, liquid nitrogen and Paris Hilton.
You have just been Sharapova'd.
|
|
|
|
|
Jeremy Falcon
|
|
|
|
|
as Homer would say: "Mmmmmm, Paris Hilton, mmmmmmm". Actually, bleeeeeeaccch!
#SupportHeForShe
Government can give you nothing but what it takes from somebody else. A government big enough to give you everything you want is big enough to take everything you've got, including your freedom.-Ezra Taft Benson
You must accept 1 of 2 basic premises: Either we are alone in the universe or we are not alone. Either way, the implications are staggering!-Wernher von Braun
|
|
|
|
|
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
|
|
|
|