|
cheers
Chris Maunder
|
|
|
|
|
There is a right way and a wrong way to perform code commenting in source code; here's what not to do. // why not?
|
|
|
|
|
Yet another person who couldn't walk the walk, yet feels qualified to tell those of us that *can*, how it should be done....
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013
|
|
|
|
|
Them as can, do; them as can't become bad teachers.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
0: Remember that adding "the dog's" means it's good
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
Quote: Don't comment on the obvious
This dogma, more than anything else, is the root of all evil when it comes to "how to comment" posts.
I couldn't even guess the number of times someone has assumed something is "obvious" but is clearly highly ambiguous, or worse, totally and utterly not obvious. I've even done it myself: made a pithy comment since I thought it was obvious and then, 6 months later, had no idea what was going on.
And then there's the "obvious" at the time and for the situation, but then times and situations change. New functionality, new technology, even the changing use of terminology means things become un-obvious very quickly.
Comment always. Comment to clarify. Comment to tell the story of what you feel the code should be doing even if it's obvious because that one comment, that one tidbit, could save a dev a week of pain or worse - a catastrophically bad assumption.
cheers
Chris Maunder
|
|
|
|
|
obvious (IMO) to avoid:
// declare variables
// implement code
#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
|
|
|
|
|
Even that much does no harm, afaics.
|
|
|
|
|
It does no good either and is annoying as hell when there's no comments saying WHY something is being done.
Don't tell me WHAT you are doing, I can read that. Tell my WHY you are doing it.
#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
|
|
|
|
|
TheGreatAndPowerfulOz wrote: It does no good either and is annoying as hell when there's no comments saying WHY something is being done.
Yes, but that's obvious, so you don't need to document it.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
LMAO. 
#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
|
|
|
|
|
In fairness, he did say but think carefully about what is obvious. He didn't clarify it very well, however, and your point is well taken.
I would add
6. Don't constantly interrupt the code with comments.
I loathe reading code with intrusive comments. This includes trailing comments, which are rarely appropriate outside of assembler. I'd rather read a paragraph that describes what a block of code does, after which the code is allowed to flow and speak for itself.
|
|
|
|
|
Still, I guess the thing is that code comments are not enforced by the compiler.
So you may end up with smth like this after some refactorings (actually a real code I've witnessed)
public void IncreaseCounter()
So I'd rather abstain from code comments unless I really need them. Lots of stuff can be fixed with the right naming and extract method or complex conditional refactoring.
|
|
|
|
|
Sorry but this is actually not related to "comment or no comment" it is more related to "lazy copy+paste and don't do it consequent"
But yes... I can give you that. Bad placed comments can be more dangerous that no commets at all.
M.D.V. 
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
|
|
|
|
|
Don't tell me what you're doing, I can read that. Tell my why your doing it.
#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
|
|
|
|
|
The system, which uses airbrushing of functional inks, enables various displays, like interactive sofas with embedded sensors to control your television, and sensors for adjusting lighting and temperature through your walls. Banksy has a UI
|
|
|
|
|
Hackers are already working on an e-mail virus that sprays solvent thinners unless the victim coughs up bitcoin.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
Adding interactive controls to a La-Z-boy might require re-branding to La-Z-er-boy.
|
|
|
|
|
This multimedia project consists entirely of original historical mission material.
Relive the mission as it occurred in 1970 Spoiler alert - there will be problems
|
|
|
|
|
Over 8,000 royalty-free images and icons will be available in Excel, Word, Outlook, and PowerPoint apps for users. In the coming months, Microsoft will be adding more premium content for Office 365 subscribers. Sharing in the bounty
|
|
|
|
|
Royalty free, but only available for suscribers 
Lucky me, that I won't be needing them 
M.D.V.
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
|
|
|
|
|
If the pandemic has left you surprisingly nostalgic for your office, imisstheoffice.eu, made by Kids Creative Agency, might be the closest thing to actually being back there. People actually miss it?
|
|
|
|
|
Maybe there was some option for standing up and tell then "You guys, couldn't you you go to discussion room, or shut up! I didn't find it. (That option is available in our real world office environment!)
|
|
|
|
|
|
did you really remember that there was that stip?  
M.D.V.
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
