Inappropriately-Appropriate Code Comments
-
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.
-
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.
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.
