|
What are the general thoughts and/or examples of 'working blue' in code comments? My thought is that, as the end user of our product never sees the comments, then it's whatever, but some do not agree (e.g. "not professional", etc., like devs tend to be "professional" anyway). For example, if I write a particularly kludgy piece of code (which is most of it  ), then I'm fond of comparing it to horse excrement, etc. Not only does it alert me and anyone else as to what's up, it also highlights that I'm aware it sucks and that it's okay to have a bit of sense of humor about it, etc.
|
|
|
|
|
Comments are there to describe the code, not your your level of frustration with it. If you want to complain, use a blog.
".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
-----
"Why don't you tie a kerosene-soaked rag around your ankles so the ants won't climb up and eat your candy ass." - Dale Earnhardt, 1997
|
|
|
|
|
Yep, use a blog or the forums at CP. Some of us do love a good rant that includes code samples.
|
|
|
|
|
I'd rather see a concise description of the code's problems. 'Colorful' language distracts the reader.
IndifferentDisdain wrote: I write a particularly kludgy piece of code (which is most of it ), then I'm fond of comparing it to horse excrement,
Instead of documenting how kludgy the code is that you write, why not work on improving it?
IndifferentDisdain wrote: like devs tend to be "professional" anyway
Professional developers tend to be, well, 'professional'.
Software Zen: delete this;
|
|
|
|
|
Comments are intended to clear up unclear code. Code should not be unclear because it is badly written, but because the problem it solves is difficult and requires some specific knowledge. That's where commenting should be used.
As such each line of comment should be treated like regular code that needs to be maintained. For example, if you change a bit of code that is commented you should check if the comment still matches the code. The less you need to maintain the better, so you best use comments only when they are really necessary (or rather, when you think they are necessary, it's a personal matter).
If you comment to much or to obvious comments are distracting and are a waste of digital ink and paperspace and only increase scrolling time.
I've written a little tip on writing good comments (or at least what I think are good comments). You might want to check it out: Write comments that matter[^]
It's an OO world.
public class Naerling : Lazy<Person>{
public void DoWork(){ throw new NotImplementedException(); }
}
|
|
|
|
|
Was reading you comments in your code in your article. I was wondering why you even bother with Alpha:
After all every learned person knows the what Alpha has to be, why not just call a spade a spade?
|
|
|
|
|
Code should not be unclear. Not even for complicated problems. If it's unclear, it needs refactoring until it becomes clear.
There are extremely rare cases when a line or a small number of lines look awkward - most often workarounds for library bugs or the like. A comment in such case is OK, to explain the implementation awkwardness, but IMO that's about it.
There's another issue about commens. Some people try to add enough comments to make the design/architecture clear from comments. That's IMO a bad idea. Usually the architecture is an issue at a level higher than the compilation unit, having comments at that level won't help.
|
|
|
|
|
I agree with you completely.
Though sometimes time (or even personal programming skills) won't permit extensive refactoring and you'll have to make it as clear as possible within a given timeframe (and/or skillset). As clear as possible might still be unclear. When you've tried everything the least you can do is comment it. Show me one application that's slightly more difficult than Hello World with no unclear code and some faith in humanity will be restored 
It's an OO world.
public class Naerling : Lazy<Person>{
public void DoWork(){ throw new NotImplementedException(); }
}
|
|
|
|
|
Florin Jurcovici wrote: There's another issue about commens. Some people try to add enough comments to
make the design/architecture clear from comments. That's IMO a bad idea. Usually
the architecture is an issue at a level higher than the compilation unit, having
comments at that level won't help.
The architecture is at two levels higher. However the design is only one level higher and it specifically drives the implementation. So implementation decisions are driven directly from the design.
And attempting to leave such comments to the design isn't going to work if the written design didn't exist in the first place, or if it was incomplete or wasn't ketp up to date. So commants at that level then can be the only source of the actual design.
Additionally since architecture drives design which drives implementation an implementation decision might have originated from an architecture need. And because it is an implementation decision explaining why that decision was made, in the implementation, is entirely appropriate and correct.
|
|
|
|
|
Programmers don't all work the same way; even when dealing in static languages and using self-documenting naming conventions, people will take away different meanings at first glance.
How about when coming across a moderately sophisticated regex? Surely a one-line comment would explain its purpose quite effectively. It also helps in maintenance/debugging if you can read in plain terms what the developer had originally intended.
Sometimes a fist in the face says more than a thousand honeyed words.
|
|
|
|
|
|
You're welcome!
It's an OO world.
public class Naerling : Lazy<Person>{
public void DoWork(){ throw new NotImplementedException(); }
}
|
|
|
|
|
Write it, send it to code review, get it back and clean it up.
Nihil obstat
|
|
|
|
|
I just gave you a 5 to counter the univoter. There, first time I've said that 
Seriously, no mercy in the lounge today, as you can see. Of course, none of us would ever, ever put colorful comments in the code. No, not us. We're professional.  laughing at all of us.
All they said is true, work on improving the code rather than colorfully but usefully commenting on it. There IS room for whit though.
Charlie Gilley
<italic>You're going to tell me what I want to know, or I'm going to beat you to death in your own house.
"Where liberty dwells, there is my country." B. Franklin, 1783
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759
|
|
|
|
|
Thanks; I was kind of surprised at some of the negative comments, personally, but such is life (I'll abstain from using the French version of this saying; considering a strong anti-French leaning of many members, I'll not risk rising their ire again ). What prompted this question was some study as to the profanity count of some MSFT project; I'll have to find it and link to it for context.
|
|
|
|
|
Oh Lord, the running anti-French thing you cannot take too seriously. Wait till the Irish and Brits get going at each other  Then comes the anti American tirade, etc, etc.
You are in "The Lounge", so you better man - up ...
Charlie Gilley
<italic>You're going to tell me what I want to know, or I'm going to beat you to death in your own house.
"Where liberty dwells, there is my country." B. Franklin, 1783
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759
|
|
|
|
|
In some of the more bizarre bit twiddling depths of my code I have comments which just say: WTF???!!!!????
It usually means I have tried to give an explanatory comment but gave up as the code isn't really anything which can be expressed in English
|
|
|
|
|
Example or it isn't true!
I've been able to explain every bithack I ever used, and many that I've never used as well. Sometimes it takes quite a lot of text to explain it in detail, such as in the case of propagating bounds through bitwise AND and OR without a loop (the version with a loop isn't trivial to explain either), but it's still expressible and removing some detail makes it "long but not too long".
|
|
|
|
|
...and if you can't explain it, you don't understand it, and no one can maintain it.
If you get an email telling you that you can catch Swine Flu from tinned pork then just delete it. It's Spam.
|
|
|
|
|
Code comments are just like Lounge comments. People consider themselves funny, witty and to have a sense of humour. This is often a delusion and tends to annoy the hell out of others.
Peter Wasser
Art is making something out of nothing and selling it.
Frank Zappa
|
|
|
|
|
Well played, sir, well played.
|
|
|
|
|
Assuming you are being paid to work for a company, then part of the long-term value in the product/source-code base may well be the extent the code is maintainable, readable, and annotated with appropriate comments that explain unusual methods/solutions/work-arounds, as well as the other functions comments usually perform.
Source-code with inappropriate personal comments might well reduce the chances of a possible future acquisition of the company, as a possibly acquiring company does a "due-diligence" technical review. I have worked at one company which was "consciously designed" from the get-go to become the "apple-of-the-eye" of a certain very large company, to become an inevitable acquisition target for the big company.
And, it was acquired, without ever becoming a "big commercial success" in its own right (to the immen$e benefit of myself, and other holders of the start-up's "fantasy stock").
What if the technical review of the source-code base of the company wishing desperately to be acquired, by the world-class programmers from the acquiring company, had come across a bunch of bizarrely off-topic comments that implied they didn't know why what they were doing, in specific cases, and contained personal ventilation of frustration : ... uhhh ... a deal-breaker ?
At that little start-up (which would certainly have failed within six-months if it had not been acquired), there was a high degree of scrutiny of all source-code by the founder, who was one of those rare geniuses who was both a world=class programmer himself, and an astute business-man able to sell venture capitalists a "field of dreams," all the while deliberately shaping the company to be an irresistible acquisition candidate by one specific very-large well-endowed company.
best, Bill
~
Confused by Windows 8 ? This may help: [ ^] !
|
|
|
|
|
When I was selling my business I went through the code prior to the source code check and changed all the "WTF" comments to nebulous but pertinent sounding ones. My main system uses bitmapped inverted indexes so there is a lot of bit twiddling and in some cases the code can explain what is happening far better than any comment in English - I used the "WTF" comments as place holders for when I did come to sell my business and needed to at least insert some comments in English in those places.
|
|
|
|
|
RugbyLeague wrote: I went through the code prior to the source code check and changed all the "WTF" comments to nebulous
And there is absolutely no possibility that you missed one?
RugbyLeague wrote: I used the "WTF" comments as place holders
Same purpose is served by using a 'TODO'
|
|
|
|
|
I am more keen to check the WTF's than the TODOs - I use TODOs for future enhancements and optimisations
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
