Inappropriately-Appropriate Code Comments
-
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
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.
-
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: [^] !
Thanks for this: a truly well-thought out and explained scenario where there could be unintended consequences. This is exactly what I was looking for.
-
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.
Nice; thanks for the warnings. I guess I'd never thought of that possibility, but sure, it could happen.
-
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.
Personally, I think these people are all way too uptight, and a little humor in comments is fine. All this "unprofessional" and "it distracts...".... Get over yourselves... Just my opinion, of course :) -MJC
Michael J. Collins Web Application Programmer
-
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...
To date, I've never used expletives in production code, comments or otherwise (I know my original question intimated that I had, but definitely not). Even if I did, I certainly wouldn't in non-comment code (we're in .NET, so it's all too easy for others to inspect the DLLs, etc.; bad things there). It seems like I remember a case of a large company where the MessageBox scenario you outlined actually happened; I'll have to research to see if I can find it again (some random article I read probably 12 months ago).
-
Years ago, a bright young programmer placed a comment in what he thought was code that would never execute. It did. In the field during a trial with a potential sale of hundreds of units. If not for the sense of humor with the client's field engineer at the time, I think we'd all have been fired. The comment was something to the effect of requiring the sacrifice of a black goat on the keyboard during a full moon. Placed by a person who had since left the company ... and we did not even know about it. Shame on us. Very tense scenario in the room when that message popped up. We were called in for a chewing out at the next available meeting. The sale did go thru, btw. A commment like that can cause a lot of heartache, even jobs, you name it. With the current jobs atmosphere these days, it's best to keep our frustrations to ourselves. I know of some employers who monitor comments on blogs even when you are not at work. It'd be a pain to work for such folks but they do exist.
I used to work for just such folks; for example, on my personal facebook page (which is locked down to all non-friends), a co-worker commented on my status last night that team member A was busy that night with a lot of support calls, etc., to which I commented "yeah, she's a worker" or something to that effect. The next morning, I was called in for an "unofficial" warning about discussing work matters on facebook. Treacherous #$$##$#s.
-
Gee, you're so quick to impugn my competence on the basis of a brief summary of a large, complex problem! Look at all those assumptions about what I did and didn't do! And you lambasted me in such magnificent grammar, at that. Did you write that in English, or did you use a freeware Gibberish-to-English translation program?
You're obviously destined for great things. Just keep on as you've begun, and no one will be in any doubt about your percipience, intelligence, or people skills. Of course, that might result in your freezing to death in a cardboard box, but we all face choices in life. Who knows? Maybe your design and coding skills are great enough that mannerly folks will accept your little ways. You might want to start thinking about that.
(This message is programming you in ways you cannot detect. Be afraid.)
It's usual behaviour of guys without arguments: "gee, your grammar is bad!", but I forgive you. I count on the info you gave. Or info you accurately selected for the story. Anyway it's enough to conclude: under GOOD management there is no SUCH comments like Steve's. Do you agree? Or may be you'll invait that "Steve" and he will explain your "large, complex problem"? (which is solved by "two segments of Steve's code" - haha) Obvious that I'm not an English native speaker, was it TOO hard to realise it?? Your chineese is a way worse than my English, so what?
-
Completely agree: even program itself is written NOT FOR CPU, but for us, humans! And as in verbal conversation, you express yourself according to your emotions. Why comment is an exception? If I hate MS for idiotic "if (myWindow.ShowDialog() == true)" why I cannot say it? (if you didn't catch the point, ShowDialog() now returns.... absolutely stupid "bool?" type!!) With emotions, jokes, etc we say our followers "hey, it's not only 0/1, it's our thoughts, dude!". :)
Thornik wrote:
If I hate MS for idiotic "if (myWindow.ShowDialog() == true)"
This has bothered me since I began professional development 2 years ago; it honestly took me quite (an embarrassingly) long time to figure out that a Show...() method actually had a boolean return value. It made no sense to me then, it makes no sense to me now, and even though I've accepted it, it'll likely not make sense to me in the future. Why not name it ConfirmDialogBox or something like that? That signifies it's looking for some sort of confirmation, thus returning a boolean value.
-
Wow. Sounds like a bunch of old guys writing their opinion[s]. I'm only 55 and been doing this for a long time. Write what you want. Comments should, yes, be informational first and foremost. But throwing in a bit of humor never hurt anyone. Indeed, I throw humor in because someday, sometime someone will chuckle. I've had people thank me for a bit of humor years down the road, long after I'd forgotten the comment. It's fun, Man! And as for "swear words" ... all I can say is it sure seems that a lot of people are pretty uptight about "bad" language. In the words of the late, great George Carlin "it's only words".
I like to write code with humor in it. I also look forward to hearing a chuckle when somebody comes across a gem I wrote. It makes my co-workers more likely to want to review the code/do a bug fix/or participate in development. Our unwritten rule was there was nothing crude/foul language should somebody unintended read the comment. Getting in the practice of writing comments in the code makes the code easier to understand when people see the code for the first time. I remember that about 1/3 of every program I wrote was comments and white space. The result of our comments made a more plesant workplace. I do want to point out that most of the comments in the system were related to the code, but we can't be serious all of the time! Hogan
-
Wow. Sounds like a bunch of old guys writing their opinion[s]. I'm only 55 and been doing this for a long time. Write what you want. Comments should, yes, be informational first and foremost. But throwing in a bit of humor never hurt anyone. Indeed, I throw humor in because someday, sometime someone will chuckle. I've had people thank me for a bit of humor years down the road, long after I'd forgotten the comment. It's fun, Man! And as for "swear words" ... all I can say is it sure seems that a lot of people are pretty uptight about "bad" language. In the words of the late, great George Carlin "it's only words".
I personally agree with this 100% but wanted some additional viewpoints (and some of the counterpoints were actually well-reasoned and insightful); fortunately, our dev shop is just the principal and me (I'm the only employee to date), and he's of a like mind, so there's no short-term objection or anything like that. Based on all feedback, I think I can agree that swear words should be kept to a minimum, and definitely nothing insulting, derogatory, offensive, sexist, etc., but there's no reason humor can't be injected into comments as long as a.) it does not interfere with the message (hopefully enhances it) and b.) it fits the effective culture of the office.
-
It's usual behaviour of guys without arguments: "gee, your grammar is bad!", but I forgive you. I count on the info you gave. Or info you accurately selected for the story. Anyway it's enough to conclude: under GOOD management there is no SUCH comments like Steve's. Do you agree? Or may be you'll invait that "Steve" and he will explain your "large, complex problem"? (which is solved by "two segments of Steve's code" - haha) Obvious that I'm not an English native speaker, was it TOO hard to realise it?? Your chineese is a way worse than my English, so what?
Your reading comprehension is as poor as your power of reasoning. My argument is principally with your assumptions about what did and did not occur, all of which are wrong. Your arrogance is typical of a young engineer who has never had supervisory responsibilities. After all, everyone knows how to do the boss's job better than the boss does!
Inasmuch as I am considered one of the best front-line supervisors in my rather large company -- engineers constantly plead to be allowed into my group -- I forgive you for your presumptuousness and immaturity, though I do hope you'll grow out of them.
Finally, I don't speak nor write Chinese, but if I found it desirable to do so, I'd learn it thoroughly enough to do it properly. It's a matter of respect...but it seems that your deficiency in that regard extends to butchering other people's languages while delivering unsubstantiated insults to their competence.
Have a nice life. You'll understand that, I trust? The words are nice and short.
(This message is programming you in ways you cannot detect. Be afraid.)
-
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 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
-
Thornik wrote:
If I hate MS for idiotic "if (myWindow.ShowDialog() == true)"
This has bothered me since I began professional development 2 years ago; it honestly took me quite (an embarrassingly) long time to figure out that a Show...() method actually had a boolean return value. It made no sense to me then, it makes no sense to me now, and even though I've accepted it, it'll likely not make sense to me in the future. Why not name it ConfirmDialogBox or something like that? That signifies it's looking for some sort of confirmation, thus returning a boolean value.
-
Thanks for the feedback!
You're welcome!
It's an OO world.
public class Naerling : Lazy<Person>{
public void DoWork(){ throw new NotImplementedException(); }
} -
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(); }
} -
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.
Consider that the code you're writing will be delivered to the client after it has been completed to be maintained by their own IT staff. Imagine how colorful comments may affect the image of the company you work for. Better yet, imagine you inherit a project written by someone else that besides having some crappy code, also has these type of comments. How would you feel about the original developer? It's no shame to have some bad code, but it would transmit a very professional image if you acknowledge it and point out it should be improved. It can tell other developers that you, the original writer, are a professional and mature developer instead of looking like a child that does not take work seriously.
To alcohol! The cause of, and solution to, all of life's problems - Homer Simpson ---- Our heads are round so our thoughts can change direction - Francis Picabia
-
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, 1997Yep, use a blog or the forums at CP. Some of us do love a good rant that includes code samples.
-
Wow. Sounds like a bunch of old guys writing their opinion[s]. I'm only 55 and been doing this for a long time. Write what you want. Comments should, yes, be informational first and foremost. But throwing in a bit of humor never hurt anyone. Indeed, I throw humor in because someday, sometime someone will chuckle. I've had people thank me for a bit of humor years down the road, long after I'd forgotten the comment. It's fun, Man! And as for "swear words" ... all I can say is it sure seems that a lot of people are pretty uptight about "bad" language. In the words of the late, great George Carlin "it's only words".
It all depends. It all depends on who will ever read the code. Sometimes we can't predict where the code will land and sometimes we know the code will land on the hands of very important customers. Sometimes I believe we should refrain ourselves from our humor urges for the sake of our professionalism, even though we may think it doesn't hurt anyone. It's like going to a job interview with slippers and shorts. We know it does not change our skills or capabilities but it may cost the job opportunity. I've witnessed very skilled people failing to be hired because they didn't pay attention to "look professional".
To alcohol! The cause of, and solution to, all of life's problems - Homer Simpson ---- Our heads are round so our thoughts can change direction - Francis Picabia
-
Consider that the code you're writing will be delivered to the client after it has been completed to be maintained by their own IT staff. Imagine how colorful comments may affect the image of the company you work for. Better yet, imagine you inherit a project written by someone else that besides having some crappy code, also has these type of comments. How would you feel about the original developer? It's no shame to have some bad code, but it would transmit a very professional image if you acknowledge it and point out it should be improved. It can tell other developers that you, the original writer, are a professional and mature developer instead of looking like a child that does not take work seriously.
To alcohol! The cause of, and solution to, all of life's problems - Homer Simpson ---- Our heads are round so our thoughts can change direction - Francis Picabia
In our case, we develop an in-house application that we sell to financial institutions, so there's no code delivery to clients, though I 110% agree with you that any delivered code should be devoid of inappropriate comments. I'm definitely in the camp to not include comments unless they are necessary, particularly to explain complex logic or to explain some weird workaround that had to be implemented. Both of these cases are ripe for hacks and kludges, IMO. So, yes, admitting the problem is the first step, so to speak, but I also think it's good to have a bit of sense of humor about it.
