Inappropriately-Appropriate Code Comments
-
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 -
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.
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; -
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 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(); }
} -
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.
Write it, send it to code review, get it back and clean it up. :)
Nihil obstat
-
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.
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. ;P 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 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
-
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.
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
-
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.
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
-
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:
// Alpha is simply the answer to life, the universe and everything.
After all every learned person knows the what Alpha has to be, why not just call a spade a spade?
-
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.
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: [^] !
-
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.
I very rarely include expletives in comments, it is rare that I think MY code is that bad. However I will happily call the owner of some particularly bad kludge any number of expletives. It is rather embarrassing when they explain the reason and I can't come up with a better solution :-O I also make sure I include the URL of any solution I have snaffled off the interweb. This is so I don't have to explain it, the author generally does that in the supporting doco. Added bonus is they get the credit for the solution.
Never underestimate the power of human stupidity RAH
-
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.
-
I very rarely include expletives in comments, it is rare that I think MY code is that bad. However I will happily call the owner of some particularly bad kludge any number of expletives. It is rather embarrassing when they explain the reason and I can't come up with a better solution :-O I also make sure I include the URL of any solution I have snaffled off the interweb. This is so I don't have to explain it, the author generally does that in the supporting doco. Added bonus is they get the credit for the solution.
Never underestimate the power of human stupidity RAH
Mycroft Holmes wrote:
also make sure I include the URL of any solution I have snaffled off the interweb
Indeed. I have a wikipedia link in one spot for an algorithm I used.
Software Zen:
delete this; -
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".
-
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. :thumbsup:
If you get an email telling you that you can catch Swine Flu from tinned pork then just delete it. It's Spam.
-
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.
I worked for a while at an "international" company based near Munich. We had people from 43 different countries all working in English (more or less). It was very interesting, especially when you read the comments on some code maintained by a multilingual Frenchman, a multilingual German, a multilingual Englishman, a bilingual Italian, a bilingual Pole, a bilingual Spaniard and a poor American who only spoke the US version of English. The comments were (theoretically) in English - although the grammar was all over the place - but the "meaningful" variable and function names, etc. were multi-lingual! You needed the comments to explain the meaningful names! Yes, I was the Englishman.
- Life in the fast lane is only fun if you live in a country with no speed limits. - Of all the things I have lost, it is my mind that I miss the most. - I vaguely remember having a good memory...
-
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.
IndifferentDisdain wrote:
My thought is that, as the end user of our product never sees the comments, then it's whatever, but some do not agree
The problem of course is that is an assumption. Some possible serious problems... As a specific example some customers require as part of sales agreement the ability to inspect source code and even receive a copy of it. So the Acme company gets your code where you have a comment that says "This only exists because the idiots at Acme don't know what they are doing". A developer from a client company is tasked with helping developing an adaptor in house and in doing so has access to the code base. The developer is John Doe. The comment in the code is "Moron developer at Acme, John something, seems to think that this should return zero instead of null". The new developer, a woman, starts and takes over maintenance of a project that you are more than happy to hand off. The code is sprinkled with comments like "This code is just as temperamental as a woman on PMS". She complains. And you have a EOC complaint in your record. Even worse she sues and you are called to testify so there is a public record of a EOC complaint initiated by you. Of course up until the sh*t hits the fan it all seems like just a bit of fun.
-
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'
-
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
-
IndifferentDisdain wrote:
My thought is that, as the end user of our product never sees the comments, then it's whatever, but some do not agree
The problem of course is that is an assumption. Some possible serious problems... As a specific example some customers require as part of sales agreement the ability to inspect source code and even receive a copy of it. So the Acme company gets your code where you have a comment that says "This only exists because the idiots at Acme don't know what they are doing". A developer from a client company is tasked with helping developing an adaptor in house and in doing so has access to the code base. The developer is John Doe. The comment in the code is "Moron developer at Acme, John something, seems to think that this should return zero instead of null". The new developer, a woman, starts and takes over maintenance of a project that you are more than happy to hand off. The code is sprinkled with comments like "This code is just as temperamental as a woman on PMS". She complains. And you have a EOC complaint in your record. Even worse she sues and you are called to testify so there is a public record of a EOC complaint initiated by you. Of course up until the sh*t hits the fan it all seems like just a bit of fun.
jschell wrote:
some customers require as part of sales agreement the ability to inspect source code
I've had that happen to me. Twice. By the same sales twit. In both cases she sold the rights to our source code in a sales contract. In the first case, the customer just needed some documentation that wasn't part of the standard kit. In the second, a few e-mails between the customer and yours truly helped resolve the issue. This is what happens when you're a software engineer working at a hardware company. The sales twits would never dream of giving away hardware design information like schematics or CAD drawings. Software has no intrinsic value, so just give it away :mad:.
Software Zen:
delete this; -
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.
The rule is: If other people are to see or work with your code then keep it proffessional, informative and descreet. ( You don't know their religion, ethics, if they are PC (Politically Correct) or if they are easily offended.) If you are the only one that manages the code the WTE, do what ever you like. But then again.... How do you name your variables and your functions? Do you follow the same ethical procedures that you use for comments...? Catch an exception and .tostring it to a messagebox and have your expletives revealed to all. Best to write all your code as it was to your Mother or Chris Maunder's Kid sister. That way you won't elephant up. Personally though I like a bit of character in comments and in var names, function names, class names, module names and indeed form names. I do know this though... Never ever write temporary violent, abuse or expletive stuff in your messagebox or any notification code, because one day you will not delete it or or comment it out, and it will Pop up on a customers machine. Comments are for other programmers or yourself. Keep pro or if just for thy then go for it... but always beware...
