Inappropriately-Appropriate Code Comments
-
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.
-
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(); }
} -
Thanks for the feedback!
You're welcome!
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.
-
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.
IndifferentDisdain wrote:
In our case, we develop an in-house application that we sell to financial institutions
I do exactly the same, except that the code stays in the financial institution. So I'd never add humor to the code I write because financial institutions tend to take stuff very seriously. If you are absolutely sure the code will never be requested by the client, then by all means, add some fun to the mess :), otherwise, I'd just not risk it. I say that because I know financial institutions require a lot of audits, including source code review for security purposes. Imagine having to review a huge code base, just to eliminate comments that may transmit a bad image of the company :sigh:
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
-
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 don't know about Inappropriately-Appropriate Code Comments, but I recently took over a project and was pouring through the code and found:
ReDim Preserve F__kMe as BS
The underscores weren't used, but you get the idea. Quite a lot of this type of variable naming.
-
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.
Show off some of your creativity, cuss it out without actually using any cuss words :) Cuss words sometimes offend coworkers, both current and future, and why would you want to do that? Besides, you never know when some suit will decide to have a peeksie at the code and be offended by the language in the comments.
We can program with only 1's, but if all you've got are zeros, you've got nothing.
-
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.
What's funny to you, may not be funny to someone else, having said that, i usually don't write colorful comments (or comments at all for that matter :zzz: ), but i wouldn't write anything beyond PG, just to be on the safe side. :)
CEO at: - Rafaga Systems - Para Facturas - Modern Components for the moment...
-
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.
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.
-
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?
Thornik wrote:
Anyway it's enough to conclude: under GOOD management there is no SUCH comments like Steve's
Wrong. Good developers tend to also have strong opinions. There is no such thing as black and white facts and there certainly is almost never time and absolutely never enough money to figure out the best solution. So opinions matter. But that doesn't mean that they are not opinions. Nor does it mean that a single opinion is in fact best. But businesses can't wait for the best to be proven. They need a solution now or even yesterday and so either someone must acceed or a manager must step in at times. And your comment completely ignores the fact that, as with all human endevours, humans are, by definition, average. That means developers and managers are almost always average. Thus managers are not excellent but neither are the developers that they manage. And that fact isn't helped by the emotional state of developers of which a large percentage think they are above average. And thus who consider that their opinion should be given more weight.
-
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".
Gary Huck wrote:
But throwing in a bit of humor never hurt anyone.
Jokes can be consideration in EOC complaints. So someone can end up getting hurt. And just because you think it is funny doesn't mean that everyone or even anyone else will consider it funny.
Gary Huck wrote:
And as for "swear words" ... all I can say is it sure seems that a lot of people are pretty uptight about "bad" language.
I doubt most offensive comments containing nothing but swear words. The swear words are used to provide an emphasize for some opinion expressed in the comment.
-
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
Fabio Franco wrote:
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".
Thats a good analogy. You can't know what the people on the other side of the table are like until long after it matters.
-
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.
People tend to make comments in code (and other areas) where they don't think anyone will ever see them. That is not always the case. At one of my previous jobs we flew to Chicago to look at a system to do monitoring for us. While we were there and taking the 'Grand tour' we noticed one of the techs had a screen up and had put some 'inappropriate' comments about one of their customers. As it turned out that customer had a close working partnership with my company. The end result was they lost both our business and that of our partner. At the time it was several million $ per year. IMHO - don't put anything in comments you would not say out loud to a group of people.
