Beta

Slashdot: News for Nerds

×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

If the Comments Are Ugly, the Code Is Ugly

CmdrTaco posted more than 4 years ago | from the what's-wrong-with-minimalism dept.

Programming 660

itwbennett writes "What do your comments say about your code? Do grammatical errors in comments point to even bigger errors in code? That's what Esther Schindler contends in a recent blog post. 'Programming, whether you're doing it as an open source enthusiast or because you're workin' for The Man, is an exercise in attention to detail,' says Schindler. 'Someone who writes software must be a nit-picker, or the code won't work ... Long-winded 'explanations' of the code in the application's comments (that is, the ones that read like excuses) indicate that the developer probably didn't understand what he was doing.'"

cancel ×

660 comments

Becoming a Nigger (-1, Troll)

Anonymous Coward | more than 4 years ago | (#30116538)

HOW TO BE A WORTHLESS, VILE, AMERICAN YARD-APE!!!!
  • Slink around, shuffling your feet and bobbing your neck like the lazy retard you are.
  • Walk down the middle of the street because you don't know what a sidewalk is for.
  • Hang out at carwashes and mini-marts because everybody knows these are the best places to be a dope, I mean dope.
  • If you're a nigger bitch, shit three nigger babies into the world before 17 years of age. This assures that welfare money will support you, so your nigger men have more time to commit crimes.
  • And give REAL honest black people a bad name.
  • Oh yes, make sure each nigger baby has a different father.
  • Bastardize the English language in the name of nigger culture.
  • Make sure that several terms have multiple meanings and others have ambiguous meanings and that only 50% of nigger words are even complete words. Real niggers will know what you're trying to say.
  • As a culture, make sure there are always more blacks in prison than in college at any given time.
  • Hang out in packs of 10 to 15 and make sure everyone acts as annoying as possible. This helps to promote nigger individuality.
  • Always talk loud enough so everyone in the 'hood can fucking hear you, and if they are niggers, they will know what your saying, bro.
  • Wear clothes that are 10 sizes too big, making sure the pants hang off your ass.
  • Park at least 5 junk cars in your yard while being careful not to use the driveway. It's OK to abandon them in the street as long as it's in front of someone else's crib.
  • Exaggerate every motion, every tonal inflection and grab your dick a lot.
  • Do drugs, sell drugs, make drugs. Okay, don't REALLY do this, but it IS what niggers do.
  • Turn your backyard into a junk yard. If you don't have a backyard, turn your mother's into a junk yard.
  • Travel around leaching off relatives, friends, salvation armies.
  • Drink cheap wine and malt liquor every day, forgetting that "malt liquor" is just fortified cheap beer.
  • If you're a nigger buck: fuck anything that moves, no matter how ugly she is. After two 40oz, even the ugliest, fattest nigger bitch will look good.
  • Be charitable and covet fat, ugly white chicks. After all, they're niggers too. They can't help being so undesirable to white men that they have to fraternize with black dudes on a 20/20 trip. And white ho's are a special trophy too, especially the not so ugly ones.
  • Spray paint everything in sight with scribbles that mean nothing to white people but mean things to fellow niggers (except niggers from another hood who will probably go after you for tresspassing on their turf).
  • Use the term "motherfucker" in every sentence. It's one of the most versatile words in the nigger language, being a noun, verb, adjective and complete mini-sentence in event you run out of thoughts.
  • Stop in the middle of the street, blocking all traffic to converse with fellow niggers and have complete disregard for everyone else.
  • Overcharge customers at Taco Bell and pocket the difference.
  • Drive your car while slouched so low that you can barely see over the wheel (gangsta drivin').
  • Get a job under affirmative action. Then sit around all day pretending that you earned the position and that the other co-workers respect you. Whenever you fuck up, scream "racism!" & hope you get enough Generation X liberals in the jury.
  • Never, I mean NEVER, take any responsibility for your actions. Always blame others including Asians, Latinos, Mexicans, and especially Whites for your sorry ass stupid lives.
  • Be sure to get a dog, tie it up in the cold and mud and neglect it until it dies. Then start all over again. Cash must be used because you long ago fucked up your credit and checking account.
  • Cram 5 generations into a two room government apartment and still be able to neglect your kids.

Then you too can be a true nigger, and anyone who finds any fault with anything you do is automatically a racist. They don't dislike what you do and wish you would do something better with your life, nor do they wish you would realize that other people exist and should be treated with respect. No, they're just racists who hate you because of the color of your skin, and everything bad in your life is their fault. You nigger.

The comment may also be complex.. (5, Insightful)

Oxford_Comma_Lover (1679530) | more than 4 years ago | (#30116558)

An explanation may be long if it is explaining something complex that the code is doing. A long-winded comment may also be a precise one, rather than a general one: rather than an excuse, this may be an explanation.

Re:The comment may also be complex.. (1, Informative)

Anonymous Coward | more than 4 years ago | (#30116580)

complex perhaps, but usually most comments are just plain irrational.

Re:The comment may also be complex.. (4, Funny)

Rick the Red (307103) | more than 4 years ago | (#30116652)

I once coded a function that varied depending on what quadrant (+x,+y; -x, +y; -x,-y; +x,-y) it was in. I couldn't get it to work right in the second quadrant, but finally got it working by chance and said so in my comments. The code worked, but I didn't understand why and said so. Is that bad coding? It worked!

Re:The comment may also be complex.. (2, Insightful)

cream wobbly (1102689) | more than 4 years ago | (#30116720)

It's good prototype code, but it's bad release code.

Was it mathematically different code for each quadrant, or was it conceptually different? In other words, why couldn't you pull the code from the fourth into the second, and swap x and y?

Re:The comment may also be complex.. (5, Insightful)

Anonymous Coward | more than 4 years ago | (#30116724)

It worked!

Are you sure about that? Did you really have enough of an understanding of the conditions to make that statement?

Chances are, it worked in the subset of cases you understood, and maybe in the subset of cases that the app needed at the time. In the future, though, all bets are off ...

Re:The comment may also be complex.. (2, Insightful)

ircmaxell (1117387) | more than 4 years ago | (#30116726)

The thing that I find a lot of developers don't understand is the difference between "Good" and "Good Enough"...

In your example, the code you got working for -x, +y may not have been "Good", but if it passes the Unit Tests, then how is it really bad? Could it be optimized? Sure...

Those that seek perfection are destined to a life of search. Those that seek 'working' are destined to a life of success...

Re:The comment may also be complex.. (3, Insightful)

Anonymous Coward | more than 4 years ago | (#30116906)

That's true with anything, though. There often comes a point at which further improvements just aren't worth the effort, no matter what product you're working with. With rare exception, where tolerances in engineering are extremely slim, your work only needs to fall within the tolerances of the person you're working for.

Now, if you're a good coder, and your code is already pretty 'perfect', that's great. Many programs benefit from optimization even if they worked satisfactorily to begin with, too. Don't expect that every program you make has to be perfect, though. Those kinds of expectations are totally unrealistic.

Re:The comment may also be complex.. (1)

Chris Mattern (191822) | more than 4 years ago | (#30117026)

if it passes the Unit Tests, then how is it really bad?

If you believe that passing the unit tests means the code is acceptable and bug-free, you are fool and I don't want you touching any code I am responsible for.

Re:The comment may also be complex.. (5, Insightful)

Abcd1234 (188840) | more than 4 years ago | (#30117028)

In your example, the code you got working for -x, +y may not have been "Good", but if it passes the Unit Tests, then how is it really bad?

How is it bad?? Christ, the metric for "good" code isn't that it simply "works". It also needs to be readable, comprehensible, and maintainable. If you can't understand how your own code works, it's bloody obvious it fails on at least one of those metrics.

Besides which, unless you are 100% positive that your unit test covers *all* cases, the fact that your code passes tells you nothing about it's correctness.

You know, back in my university days, we used to scoff at the morons in the labs who would, quite literally, randomly hack their projects until they worked. I never dreamed that some would consider that a valid development methodology out in the real world. Apparently there *is* a dark side to a high-quality unit test suite... it gives idiots a false sense of security and justifies their idiotic development practices.

Re:The comment may also be complex.. (5, Insightful)

YXdr (1396565) | more than 4 years ago | (#30117134)

... but if it passes the Unit Tests ...

That kinda presumes that the unit tests are good, doesn't it? Which means that somewhere, somehow, somebody has to know what problem they are trying to solve.

Defining 'good enough' is really tough. I've seen perfectionists get bogged down, but even more often, I've seen folks that invoke the 'it's good enough' mantra as a cover for sloppiness and incompetence.

Yes, that's bad coding (5, Insightful)

Frequency Domain (601421) | more than 4 years ago | (#30116852)

I once coded a function that varied depending on what quadrant (+x,+y; -x, +y; -x,-y; +x,-y) it was in. I couldn't get it to work right in the second quadrant, but finally got it working by chance and said so in my comments. The code worked, but I didn't understand why and said so. Is that bad coding? It worked!

If you don't understand why it worked, then you don't know how it worked. Consequently, you have no idea under what circumstances it won't work. Unless your unit tests enumerated every possible set of inputs, you don't actually know it worked. Just because code works for some inputs doesn't mean it works.

Re:The comment may also be complex.. (5, Insightful)

Abcd1234 (188840) | more than 4 years ago | (#30116892)

The code worked, but I didn't understand why and said so. Is that bad coding? It worked!

Yes. It's bad coding. Very very bad coding. And, no offense, but it indicates intellectual laziness on your part.

Any developer worth their salt would spend the time to understand *why* their code is mysteriously working, rather than just throwing up their hands and moving on, as a) it might be working for your test cases but still be incorrect, and b) anyone coming along later will be hosed, as if you couldn't understand it, there's a good chance they won't be able to, either. And of course, d) any developer worth their salt *wants* to know why their code is working, simply because it's interesting and *part of their job*.

Re:The comment may also be complex.. (1)

haystor (102186) | more than 4 years ago | (#30116996)

And while you're spending your time figuring out why something that isn't broken works, he is coding something that you aren't coding at all. Sure, coding until it passes isn't the ideal, but it's a whole lot better than not coding at all (you).

Re:The comment may also be complex.. (4, Insightful)

Abcd1234 (188840) | more than 4 years ago | (#30117076)

And while you're spending your time figuring out why something that isn't broken works, he is coding something that you aren't coding at all. Sure, coding until it passes isn't the ideal, but it's a whole lot better than not coding at all (you).

Bullshit. Software development isn't just about "coding". It's about producing software that's functional and maintainable. "Hacking it until it works" is completely antithetical to those goals.

Frankly, morons like you are the reason the industry is laughed at by other, more formalized disciplines. Could you imagine what we'd do to a bridge builder who just tacked stuff on until it kinda sorta stood?

Re:The comment may also be complex.. (5, Funny)

characterZer0 (138196) | more than 4 years ago | (#30117016)

Unless your code is running in IE5 or IE6. Then you get it to work by chance, and do not ever touch it again.

Re:The comment may also be complex.. (1)

Jared555 (874152) | more than 4 years ago | (#30117106)

And keep notes for yourself so you know to make sure it is someone else who has to work on that project next time something needs changed so you aren't going to be blamed for the guarant.... possible issues

Re:The comment may also be complex.. (3, Funny)

clone53421 (1310749) | more than 4 years ago | (#30117132)

On the basis of your username, I'm perplexed as to why you somehow failed to properly letter the items of your list. Perhaps "c) ???" should have come in front of "d) Profit!" (well, a rather long and windy version of "profit", but boils down to it basically)?

Inb4 comments about my failure to count down from 5.

Re:The comment may also be complex.. (3, Insightful)

Esther Schindler (16185) | more than 4 years ago | (#30116928)

I agree with cream wobbly that it's good prototype code but bad release code. On the other hand it's okay with me that you explained the difficulty in the comments because that fulfills the purpose: You're communicating with the next developer who looks at the code.

If you managed to get it to work (you think, anyhow), it may still be buggy; and the "Well, I THINK so..." in the comments will be an arrow to "probable source of application meltdown" for someone who comes in to debug.

There's a difference between writing a good explanation that happens to be long, and a rambling list of excuses. Yours sounds like the former. IMHO.

Re:The comment may also be complex.. (4, Insightful)

gstoddart (321705) | more than 4 years ago | (#30116746)

An explanation may be long if it is explaining something complex that the code is doing. A long-winded comment may also be a precise one, rather than a general one: rather than an excuse, this may be an explanation.

I have known several people who point out that if it really does require that complicated of an explanation, you might need to re-factor your code and make it less arcane. Of course, not everything can be simplified to the point where it's obvious when you read it, but I've definitely seen a lot of code that could/did benefit from changing it to make it more straight-forward and readable.

In general though, I agree with the article -- I've known more than a few developers who barely if ever comment code, and claim that it should be obvious from the code. As such, their comments (what there are) tend to be fairly random and not helpful. I once saw a comment that said "die lamer die" with no explanation whatsoever. "Add 1 to count" is also fairly useless.

Me, I always write the comment for a function/method before I've started writing the body of the method. Because, even if it's just me maintaining the code, I want to know what it was there for in the first place.

Cheers

Re:The comment may also be complex.. (3, Interesting)

Marillion (33728) | more than 4 years ago | (#30116768)

I've always subscribed to the theory that the code explains WHAT a program should do clearly enough that even a computer understands it.

Comments should fill in the gaps and answer the questions of WHY and HOW. For example, if I'm using a common pattern or idiom, I like to highlight that. I like to use the Delegation Pattern when doing SAX parsing of XML in Java. Rather that explain what the Delegation Pattern is about, I'll just cite the pattern name, add a link, and explain the nuances of that particular implementation and move on.

Re:The comment may also be complex.. (5, Insightful)

Kell Bengal (711123) | more than 4 years ago | (#30116934)

I agree to a limit. My philosophy is to code the comments, rather than comment the code.

Comments, for me, serve as a design tool as much as an aid to understanding. You can very quickly understand what my programs are supposed to do by reading the comments; not because my code is hard to understand, but because the comments describe its function as a narrative.

Of course, if you can't understand what the code does without reading the comments, you're doing something wrong. Once coded, the comments exist to extend and clarify what the code is doing, as well as adding meta data about how things like numerical constants were calculated.

Re:The comment may also be complex.. (5, Funny)

eln (21727) | more than 4 years ago | (#30116838)

Precisely. Comments about code that the developer himself doesn't understand, usually because he employed some nasty hack and he's not sure exactly why it worked, are usually short and contain the word "magic" in them.

For example:

/* Magic happens here*/
/* Black magic */
/* Some particularly dark black magic occurs here */
/* I'm not sure why this works, but it does */
/* I went on a vodka bender last night, and this was on my screen when I woke up. I don't know what it is, but it compiles, so let's ship the fucker. We'll call it Vista. */

Or a management failure (3, Interesting)

Moraelin (679338) | more than 4 years ago | (#30117126)

Or it could be just an indication of a management failure.

A couple of years ago I was brought in to save a project that was hopelessly behind schedule and getting nowhere. Pretty quickly I got the idea that whenever I check something into CVS, it gets re-checked by a really helpful girl there, richly decorated with comments. (Now I do comment classes and methods extensively, as well as places where higher elven magic was used, but I do _not_ write stuff like that now I'm iterating through a node's children. If you need a comment to understand that "for" loop, then there's something deeper wrong with my code.)

But, anyway, stuff like a line that said "if (currentNode.isRootNode())" had been decorated with the obviously helpful comment "// when the current node is the root node". I'm still at a loss as to what extra info is conveyed by that comment, since just reading the code out loud gets you almost the same sentence and definitely the same meaning.

And it went like that for every single line. Every single assignment, trivial loop, etc, was dutifully duplicated in that line's comment.

Turns out, they were asked to comment their code extensively, and judged basically by quantity. So she was just abiding by the rules.

Re:The comment may also be complex.. (1)

Z00L00K (682162) | more than 4 years ago | (#30117136)

Some mathematic formulas appears simple by themselves, but do the work that did result into the formula E=mc2 and you will realize that it takes some work to end up there.

But comments for their own sake - no, that's not necessary.

As for grammatical errors - it also depends on the native language of the programmer. Some coders does write good code, but their skill in English sucks big time - sometimes it would have been better if they hadn't written the comment at all.

Comments are good (5, Insightful)

Anonymous Coward | more than 4 years ago | (#30116564)

Comments are good for many reasons:
1. Showing the next person what you were doing.
2. When you have to explain what you are doing, it helps you to discover possible errors in your code. Particularly logic errors.
3. It helps you if you have to come back and look at it in a few years so you will immediately have an explanation of what you were doing.

Of course for those of us who code perfectly the first time, they aren't really needed. :-)

Re:Comments are good (0)

Anonymous Coward | more than 4 years ago | (#30116900)

Comments? What comments?

JK

Actually, when I need to learn what someone else's code does, the first thing I do is delete the comments. I don't care what this person *THINKS* the code does, I only care what the code REALLY does.

Re:Comments are good (1)

Jared555 (874152) | more than 4 years ago | (#30117148)

2. When you have to explain what you are doing, it helps you to discover possible errors in your code. Particularly logic errors.

What if the logic error was in the choice you made not to comment that piece of code because its function should be obvious to anyone working on the project?

Co-workers (5, Insightful)

Tomun (144651) | more than 4 years ago | (#30116574)

Long-winded 'explanations' of the code in the application's comments (that is, the ones that read like excuses), indicate that the developer probably didn't understand what he was doing.'

Or that he's forced to work with people that don't.

Re:Co-workers (5, Insightful)

garcia (6573) | more than 4 years ago | (#30116712)

Or he's being a good employee and doing the right thing to ensure:

1. One to three years from now when the code needs to be revisited by him that he can quickly assess the code without thinking about it too much.

2. Long after he's gone another employee can come across the code and easily understand what was done and why.

3. Comments, to me, are like writing out all the steps in a math problem. Just because you arrived at the correct answer on the face of things does not mean that you understood what you did. Documentation proves, in many cases, that you did in fact know what the fuck you were doing.

--

If you don't like comments, fold them out of the way and be done with it. I just don't see the problem here.

Re:Co-workers (2, Insightful)

Anonymous Coward | more than 4 years ago | (#30116984)

Comments need maintained. If I change your code but don't think to change your long-winded comment then the next person may read your comment and not realize that it is out of date. If you had left a one-liner right where I was making the code change I probably would have seen it and modified it correctly.

Re:Co-workers (5, Funny)

ari_j (90255) | more than 4 years ago | (#30116744)

I always write long comments that either have no relation to the surrounding code or tell outright lies about it.

Re:Co-workers (1)

cream wobbly (1102689) | more than 4 years ago | (#30116758)

Or that he's writing code that will be read by someone he doesn't get to explain the code to.

Re:Co-workers (1)

Abcd1234 (188840) | more than 4 years ago | (#30116834)

Well, I think the parenthetical is actually the key bit. I find when I'm implementing a complex algorithm, I'll write out a fairly long-winded comment that explains, in prose, what the code is doing, and then in the code itself, I'll include comments for the trickier bits. I do this because I find that a bunch of small comments in a routine is harder to conceptualize, as you have to assemble the global picture yourself. But a large comment at the start that sets the stage and outlines the algorithm takes care of that for you, and the inner comments then make more sense within that framework.

But this is *very* different from a large comment that comes down to, as the author puts it, an "excuse". OTOH, I can't say I've ever come across such a thing... a developer embarrassed by their code is far more likely to not document it at all, rather than take the time to justify themselves.

comments explain what isn't there (3, Insightful)

Russ Nelson (33911) | more than 4 years ago | (#30116586)

Comments exist NOT to explain the existing code, but to explain all the other code that could have been written, but wasn't. They also point to things like test cases (which if your language doesn't suck, you can put in line), and explanatory standards documented elsewhere.

Re:comments explain what isn't there (1)

Kenja (541830) | more than 4 years ago | (#30117040)

I always add // And then a miracle happens!

bad spelling in variables/etc get me (3, Insightful)

i.r.id10t (595143) | more than 4 years ago | (#30116600)

For me, it is bad spelling in variables and such. Or correct but "alternative" spellings - like honor_no_cache vs. honour_no_cache

Working with fellow students in a group (with one student being from England) brought this out, and in general poor spelling - category vs. catagory, etc.

Fortunately mostly fixable with find/replace, but still a bear to deal with.

Re:bad spelling in variables/etc get me (1)

pem (1013437) | more than 4 years ago | (#30116682)

Yes, back in the 90's, I worked with a junior developer who thought that everyVariableMustTellItsOwnStoryIncludingItsLifeHistoryInItsName. He misspelled one of these gems, and I was grepping for a solid half hour before I figured out why I couldn't locate it, after glancing at the name in one of the source files.

Re:bad spelling in variables/etc get me (0)

Anonymous Coward | more than 4 years ago | (#30116718)

in general poor spelling - category vs. catagory, etc.

Ugh. Now this is an excellent example. Even if your code is great in every other respect, this kind of error makes it unusable shit. And in reality, it's a strong indicator that it's probably written by a moron and will be unusable in many other ways.

Or correct but "alternative" spellings - like honor_no_cache vs. honour_no_cache

Like any other style issue, pick a convention a stick with it. 'Murkins have no trouble using and contributing to OGRE, even though it uses British spelling extensively. As long as it's consistent, it doesn't really matter.

Re:bad spelling in variables/etc get me (1)

ari_j (90255) | more than 4 years ago | (#30116786)

Find/replace is dangerous in that situation, because it's possible that the correct spelling has been used for something else. I really despise bad spelling in variable and function names, and really in general in life, but you have to watch out for the case where honor and honour are truly different variables.

Re:bad spelling in variables/etc get me (4, Informative)

cream wobbly (1102689) | more than 4 years ago | (#30116854)

I refer you to... the infamous "HTTP_REFERER".

Re:bad spelling in variables/etc get me (1)

TheRaven64 (641858) | more than 4 years ago | (#30116976)

One (non-)word: creat().

Re:bad spelling in variables/etc get me (1)

BrotherBeal (1100283) | more than 4 years ago | (#30117010)

I see this as a corollary to a phrase a Latin professor of mine used to use all the time: "Clarity of grammar is clarity of thought."

If you haven't taken the time to think through what you mean in order to translate it from concepts into words, then there's a high probability that you have missed something at the conceptual level and are hiding it in the noise and ambiguity of language. Misspelled words such as variable names or even misspellings in comments, ESPECIALLY when they're not consistently misspelled, strike me as the same sort of disregard for the rules of the system and throw up a big red flag that something may not be as it should. At best, it's an impediment to grep, but frequently I find that misspellings in and around code mean that there is more work to be done.

My comments are pretty works of art (0)

Anonymous Coward | more than 4 years ago | (#30116606)

/*
  * get_tail(node* list)
  * gets the tail!
  */

Damn you racist filter!
you're doing it as an open source enthusiast or because you're workin' for The Man, is an exercise in attention to detail,' says Schindler. 'Someone who writes software must b

Re:My comments are pretty works of art (1)

ari_j (90255) | more than 4 years ago | (#30116908)

/*
* get_tail(node * list)
*
* This function destructively sorts the list with the tail element
* as the new head of the list and the remaining elements
* sorted according to their hamming distance from the tail element.
*/
node * get_tail(node * list) {
/* The code here does nothing of the sort, and actually returns the
* element with the highest-valued md5 hash, but only after freeing
* the original list. */
}

Seems reasonable (5, Interesting)

jgtg32a (1173373) | more than 4 years ago | (#30116610)

Comments do require a bit of effort and time commitment. If you are willing to spend time on the comments your most likely going to spend more time working the code itself.

Excuses... (0)

Anonymous Coward | more than 4 years ago | (#30116628)

The only times I find myself making excuses is when management didn't properly give the requirements or change the requirements to late in the game...so you have to make bad programming decisions as a band-aid until a complete rewrite can be done proper...just to meet a deadline that was shortened or a deadline that was insanely impossible because someone oversold your departments abilities...or a deadline that doesn't adjust to the new fangle features that were always supposed to be in there. Not everything is the prgrammer's fault in this world...in fact I think you'll find that very little of it is to be laid to rest at the programmer's feet. Expectations are high, pay is low, and management simply assumes cause there are teenage kids telling them they can write the same thing in shorter time means they know what they are talking about when they don't have the slightest clue...haven't coded anything over 500 lines of code.

Nonesense (1, Insightful)

Anonymous Coward | more than 4 years ago | (#30116666)

Many people who write code are not native English speakers. it would be silly to expect their code or comments to read like a Thomas Hardy novel.

In addition, some of us write comments first and then fill in the code. Often, in fact quite often, the code evolves past what the comments say.

Someone who wastes time producing grammer-school perfect comments is wasting time that could be better used by making the code itself better.

Re:Nonesense (1)

Yvan256 (722131) | more than 4 years ago | (#30116738)

/* What you mean, my comments not good? My comments very good! You very bad man! */

// teh code is obvius (4, Funny)

tedgyz (515156) | more than 4 years ago | (#30116670)

Comments are for wimps.

Re:// teh code is obvius (2, Insightful)

StripedCow (776465) | more than 4 years ago | (#30116960)

Hey, thanks for making that comment!

Re:// teh code is obvius (2, Funny)

JohnnyLocust (855742) | more than 4 years ago | (#30117056)

/* Comments are for wimps. */

Long-winded comments can be very useful (5, Insightful)

JoshuaZ (1134087) | more than 4 years ago | (#30116672)

I sometimes write code for number theory algorithms. Often short-cuts and little speed ups have long proofs to justify why they work. If I expect the code to be used/read by other people I'll often include these explanations (and so I don't need to bother convincing myself later if I look at the code a year later). There's nothing wrong with long comments. Moreover, given a negative attitude towards long comments, many bad programmers will likely simply respond by not commenting their code at all. That's not good.

Re:Long-winded comments can be very useful (3, Interesting)

dkleinsc (563838) | more than 4 years ago | (#30116862)

Often better than including the full explanation inline is: "Proof that this works can be found ...". Yes, it's one more reference to look up, but some of the algorithms in, say, Knuth, are long and complex proofs that really will interrupt your code reading if included inline.

A lot of good comments answer one of these questions:
  - Why couldn't this be simplified?
  - What special case is this trying to handle?
  - This looks weird. Why is it right?
  - What expectations are we demanding from elsewhere in the code?

A situation where I find myself asking any of those questions and no comment is present can be nightmarish.

Re:Long-winded comments can be very useful (1)

JoshuaZ (1134087) | more than 4 years ago | (#30116932)

That's true for standard algorithms. But sometimes one is working with an algorithm that is either too new or too obscure to appear somewhere. This often occurs most obviously when what one is coding is related to one's own research. Sometimes also the algorithms aren't that obscure but one just knows the result as a sort of folk-lore rather than peer reviewed or included in a useful book like Knuth. For day to day programming this happens surprisingly often.

Well, duh. (4, Funny)

mobby_6kl (668092) | more than 4 years ago | (#30116680)

That's also why I don't comment my code.

Re:Well, duh. (0)

NoPantsJim (1149003) | more than 4 years ago | (#30116812)

Same here. I'm the only one that touches my code. My stance is that if I can't figure it out without a comment, then I didn't know what I was doing to begin with.

Re:Well, duh. (1)

Eudial (590661) | more than 4 years ago | (#30116970)

That's also why I don't comment my code.

This is a good practice. Comments very seldom keep up with changes in the code base, so more often than not, they end up being misleading at some point in the future.

The reason people think they need to cluster bomb their code with comments is generally because they have a degree in CS, and CS classes often require such code. But that's because the professor (or rather, the TA:s) need to quickly read through 50 or so computer lab reports every couple of weeks, and doing so without comments takes ages (especially what with the more dubious code that occasionally gets handed in.)

Documenting module interfaces is generally a good thing, but actually littering the implementation with comments is quite another (unless there is some outstanding reason to do so).

Sounds right (2, Funny)

TheRaven64 (641858) | more than 4 years ago | (#30116694)

It should be obvious what the code is doing just from reading it. If it isn't, then the code should usually be refactored. Comments are for explaining why the code is doing that. If your grammar is poor in the English then it's probably poor in the code too (unless you are not a native speaker). If you make spelling errors in comments then you probably do in code too. The compiler will catch some of these, but when you accidentally type the name of an instance variable or a global instead of a local, it won't spot it. If you're not checking your comments for this kind of error, you're probably not checking your code for it either.

Just as with online comments, poor grammar displays a lack of care. Hopefully, more people will be reading your comments than will be writing them. A little effort in writing them can save a lot of effort in reading them. If someone on the Internet thinks that their time is worth so much more than their readers' time then that just makes them an asshat[1]. If a programmer thinks his or her time is so much more valuable than that of people maintaining the code then he or she is a terrible programmer.

[1] I am fully aware of the universal law that means that, by writing this, my post will have a significantly above average number of typos. Please be nice...

Re:Sounds right (1)

smallfries (601545) | more than 4 years ago | (#30116820)

Wow, zero spelling mistakes, and one minor grammatical error - you seem to have poked fate in the eye and survived.

Re:Sounds right (1)

MrSenile (759314) | more than 4 years ago | (#30116916)

Not entirely true. I've put in comments and sidelines in code when you had to put in code to get around anomalies in compilers, or sadly still, poor design decisions on 3rd party software you don't have time to work around or don't have the authority or decision to work around that you're forced to include as an API or maybe a subset library.

For example, in an older glib if you had time_t defined before a char * pointer, you could mess up with the stack on the linker.

Other platforms have certain library calls and/or function calls that are slightly different and require different methods to attack with various #ifdefs or autoconf changes. Having a bit of rhetoric to define why you did something the way you did, guarantees that the next person to pick up your code won't spend unnecessary time digesting code that a simple 20 second read followed by an 'oh yea, that's right' would solve.

In today's world, making things as fast as possible to do 'catch up' could make the difference between 'make' and 'break' in the corporate model.

See Previous Story: Agile Is (0)

Anonymous Coward | more than 4 years ago | (#30116696)

NOT using MicroSLOP. I 'm sure you the know the intended reference.

Yours In Astrakhan,
K. Trout

10 PRIN "WTF" (1)

mcgrew (92797) | more than 4 years ago | (#30116716)

This seems like a no-brainer to me. Sloppy people are sloppy and stupid people are stupid, how is this not evident? The only difference is that a lot of bugs are obvuous, when the code fails to run or runs is an unexpected way, while the bad comments won't stop the code from working, only from being understood.

There are a lot of times I'll see slashdot comments like "you might loose your mind" and I think "I hope that guy's not a programmer." Loosing your mind is quite a different thing than losing it, and like some software bugs might not be evident the first time the code is run.

Re:10 PRIN "WTF" (3, Funny)

smooth wombat (796938) | more than 4 years ago | (#30117112)

The only difference is that a lot of bugs are obvuous,

Yes, yes they are.

when the code fails to run or runs is an unexpected way, while the bad comments won't stop the code from working, only from being understood.

It took a bit, but your comment is understood.

Re:10 PRIN "WTF" (1)

dkh2 (29130) | more than 4 years ago | (#30117122)

The classic is a block of select_case logic with no default. The developer is given a static list of current cases for which results are calculable. Yet, they #FAIL to consider that the case list may be not as finite and immutable as presumed. When a new case is presented then code without a default response will fail.

I'd rather... (1)

Purist (716624) | more than 4 years ago | (#30116732)

...see somewhat verbose comments than none at all. However, a good developer should be able to provide very clear and concise comments and let the code say the rest. I think this is what the original post's point is - of the code is not concise and clear, the comments won't be either. P

Non-native English speakers (4, Insightful)

AmiMoJo (196126) | more than 4 years ago | (#30116734)

English is not most people's first language. Be glad they want to write comments in English at all.

Re:Non-native English speakers (0, Flamebait)

Rakshasa Taisab (244699) | more than 4 years ago | (#30117074)

Thank you for your understanding of the lacking language skills of us non-native English speakers.

Now take your fucking prejudices and go play wow or something.

Re:Non-native English speakers (1)

mcgrew (92797) | more than 4 years ago | (#30117080)

English is not most people's first language.

Neither is COBOL, Fortran, C, Java...

Arguments for and against (1)

NtwoO (517588) | more than 4 years ago | (#30116748)

One of the best programmers on our team can not spell to save his life. He also does not touch type (a proficiency I always considered a basic requirement when interfacing with computers for your profession). He thus proves that it is not a hard and fast rule.

That being said, we work in a company where virtually all code is reviewed. Long winded comments introduce maintainability issues, since the comment can diverge from the working in time. Extensive spelling mistakes in them certainly becomes irritating, especially since there are plenty of good editors available with spell checking included. That just points to sloppiness. Not bothering to use a tool's features shows no pursuit of excellence and that certainly places doubts on the rest.

Re:Arguments for and against (1)

mcgrew (92797) | more than 4 years ago | (#30117024)

Extensive spelling mistakes in them certainly becomes irritating, especially since there are plenty of good editors available with spell checking included

Dew knot truss you're spill chucker.

Bad spelling too often = bad thinking (1)

gestalt_n_pepper (991155) | more than 4 years ago | (#30116756)

Or at least sloppy thinking. I have no idea why this is, but as anyone who has looked at internet blogs can attest, the people who can't be bothered with proper spelling, grammar, punctuation or capitalization, or who can't differentiate between "loose" and "lose" are also (usually) the biggest idiots.

You must be joking. (1)

newdsfornerds (899401) | more than 4 years ago | (#30116760)

You expect computer people to know the difference between "your" and "you're?" Hah! Good luck with that. Most of the people I have worked with over ten years refuse to spell correctly or use proper grammar. If being literate was a requirement for employment, that could change.

Not always true (1)

cecille (583022) | more than 4 years ago | (#30116764)

Yes, spelling and grammar in comments are important for understanding, and proper spelling in variable names in particular makes it easier for developers after you to follow and track through code. However, I disagree with the generalization that long comments always mean you don't know what you are doing. Most of my code comments are 1-liners, but I always leave long comments for function headers so everyone is clear on what the inputs are. I also leave larger comments for equations that aren't immediately obvious, ESPECIALLY if the equations are coming from spec documents. A spec number, section number and explanation help developers FIND these things later and actually understand them. Spec documents in particular can be thick and it's not always easy to see at a glance how things are supposed to work. Plus, if there IS a mistake (let's face it, no one is perfect), it's way easier to track where something went wrong if you know what the start point is.

Doesn't work (2, Funny)

Yvan256 (722131) | more than 4 years ago | (#30116776)

I always try to comment my code, but then the compiler keeps telling me there's no code to compile.

I'm an expert! (5, Funny)

monkeySauce (562927) | more than 4 years ago | (#30116778)

"Long-winded 'explanations' of the code in the application's comments (that is, the ones that read like excuses), indicate that the developer probably didn't understand what he was doing.'"

That's right, I'm an expert and I keep my code comments short and sweet. Observe:

// This function kicks ass.

function kick_ass()
{
...

// This following code is like Chuck Norris. It doesn't know how to fail.

while(true)
{
...

ES is not a prrogrammer (0)

Anonymous Coward | more than 4 years ago | (#30116794)

She's a hack who likes dressing like a man, man !!

Job Security (1)

Mekkah (1651935) | more than 4 years ago | (#30116796)

I barely comment; JOB Security baby...

I do however keep a personal notes file of the few items I find interesting, or harder to work out; JUST in case I can't remember or tie together wtf I was doing.

Re:Job Security (2, Interesting)

kschendel (644489) | more than 4 years ago | (#30116930)

Yeah, good luck with that. Have a second career ready?

I once consulted on a large program that had been written in as convoluted a manner as possible, with few or no comments. The guy who wrote it used to brag about "job security". Well, when the company finally allocated a budget to replace the program, they not only fired the guy, but made sure that as many people in that industry as possible knew about it. He was unable to find a new job in programming, and last I heard, he was trying to sell cars somewhere down south.

You might have job security for a while, but it's gonna catch up with you.

Re:Job Security (1)

Mekkah (1651935) | more than 4 years ago | (#30117078)

haha I'm okay, I work for the gov and I mainly do easy scripting. I was joking for the most part, because I'm to dumb not to comment on larger apps.

But I would make a good car salesmen. Preferably used cars.

Re:Job Security (1)

dmgxmichael (1219692) | more than 4 years ago | (#30117098)

Failure to comment doesn't secure your code - it just insures your code will be thrown away when the next guy comes in. It also increases the likelihood that your pissed off prior employer doesn't give you any references.

I'm currently digging through a nightmare code base. Not only are there no comments, but there's NO INDENTING EITHER. At all. I don't see how the guy who wrote it got as far as he did but. I take that back - he did occasionally comment, but only to mark the end of loops and functions which would be obvious if he would have indented his blasted code.

The decision has been made to patch what urgently needs to be patched in his code, then can it and start over from scratch. And I and my boss have already explained in detail to two calling in programmers exactly why it would be foolish to hire the moron.

comments and complexity (1)

bigogre (315585) | more than 4 years ago | (#30116806)

Two comments:

1. Comments are there to tell WHY the code is doing what it is doing, not necessarily what the code is doing. I deal with code all the time that has comments that tell me what I can easily learn by reading the code, but they don't tell me why so when it is broken I don't know if it is because there is a subtle problem with the code or that the developer didn't know what they were doing.

2. After literally getting headaches from reading code written by other people I came up with a simple metric: The complexity of the coding solution to a problem is inversely proportional to how well the developer understood the problem they were trying to solve. In other words, someone who understands the problem will have a simpler solution than someone who doesn't understand the problem as well. You can apply this metric to things other than code, too, but it is usually very apparent with software.

Ascii Art? (1)

Spazed (1013981) | more than 4 years ago | (#30116836)

That's it! I'm making all of my comments ascii art from now on!

Too wordy (0)

Anonymous Coward | more than 4 years ago | (#30116840)

That was a long-winded blog post, which indicates he probably doesn't know what he's talking about.

I agree, with reservations (4, Interesting)

JustNiz (692889) | more than 4 years ago | (#30116868)

From 30 years of developing software, I've found time and time again that it actually does seem that people who don't know or care about the difference between "their" and "they're" are also too sloppy, unintelligent or just not anal enough to write clean, supportable and robust code.

However I feel we do need to make more allowance than the article's author did for people who did not learn English as a first language.

Existence of Comments (3, Funny)

travdaddy (527149) | more than 4 years ago | (#30116872)

If comments even exist, then the code is ugly. Code should document itself.

(Any good Perl programmer knows this.)

How much code is written by outsourcing? (2, Interesting)

dejanc (1528235) | more than 4 years ago | (#30116874)

I work for a company in Serbia and we write code for an Italian corporation which also outsources their development to Brazil and India. I'm happy if comments are in English at all. Still, we get by just fine, as long as we agree on design patterns to use and writing clear and concise code. Also, whatever happened to: "Comments should describe what the function is doing, not HOW it is doing it"?

What if... (1)

Mr.Fork (633378) | more than 4 years ago | (#30116884)

there are no comments? I was once a programmer for EDS - I was responsible for the UNIX API that back-ended our helpdesk system. It was mostly written in C. The single biggest issue I had were the contractors who we brought in who either didn't comment on their function libraries they wrote, or their comments didn't follow proper function header commenting that you get if you went to school.

The bottom line, if you don't have established code-commenting procedures and processes on how you code and a quality assurance process to ensure that code is written properly and documented, you get back what kind of 'box' you put around your programmers. Those procedures are not suppose to limit how you put smarts into programming, but establish common programming language 'parameters' all programmers use on your team. Beware of the contractor however, they tend to follow their own rules, and try to ensure their own self-worth by documenting poorly.

Bullshit! (1)

bongey (974911) | more than 4 years ago | (#30116886)

Talk is cheap. Show me the code.Linus Torvalds

I am going with Linus on this one, not some tech author nazi.
I have found too often the comments says the code does X, and it does Y. What is even better is when the code is wrong. Just love it when that happens. I have had to go as far to prove to someone in the comments that there code was wrong to accept that there code was wrong, and he are grammar nazi too, so I say bullshit on this.
Programming is a art in itself, good coders can "read" the code. Comments are nice, but they are not end all, nor a guarantee the code is correct or good.Often it can be the opposite.

All I can say is "few anecdotes don't make data" (0)

Anonymous Coward | more than 4 years ago | (#30116926)

All I can say is "few anecdotes don't make data"

Forget the comments, look at the documentation (1)

metamatic (202216) | more than 4 years ago | (#30116978)

If the documentation is incomprehensible or missing, then the software generally wasn't well thought out or planned ahead of time, but rather just grew as an accretion of hacks.

This is particularly true of API documentation. I've even encountered crackpots in the Rails community who think that you don't need API documentation if you have unit tests; their code was abysmally unreliable, unstable, and performed poorly.

Practical application of comments (1)

dkh2 (29130) | more than 4 years ago | (#30116982)

The group I work with views code commentary as a requirement of the job of the go-coder.

Initial development of a new method (procedure, function, whatever a discreet unit of functional code is called in your language of choice) begins with inclusion of a summary comment of the specification. This puts the spec where the developer is working and can use it. This comment block gets tweaked and resequenced to fit the logical and technical demands of delivering the specified result and to segregate each logical step into distinct comments.

Once functional code has been implemented and unit tested the comments are reduced or eliminated along side a focused and targeted walk through variable and method names to produce final code that is as self documenting as possible.

Comments remaining in the code are there as bookmarks/breadcrumbs, or provide insight into why a particular logical approach was taken. As for the variant spellings issue - we are a small shop in the U.S. so we tell our international employees that we use EN-US spellings. ("There is no 'U' in 'honor.' and it's 'aluminum' (4 syllables) not 'aluminium' (5 syllables).")

What about foreign coders? What about dyslexics? (1)

Viol8 (599362) | more than 4 years ago | (#30117008)

There are many coders who work in a country where the language is not their first language. Does this mean the code they write is rubbish if they make some spelling mistakes in the comments? And I've met at least 2 genius level coders who had serious dyslexia and you could hardly make head nor tail of their comments, but the code they wrote was superb.

This whole premise is just a joke. Next they'll be saying people who can't program very well wouldn't be good at writing any form of document.

Why doesn't Literate Programming catch on? (1)

WillAdams (45638) | more than 4 years ago | (#30117014)

There's a terrible irony in Donald Knuth feeling that it's an even more important development than TeX, yet outside of the TeX world, almost no one uses it:

http://www.literateprogramming.com/ [literateprogramming.com]

William

If you like that sort of stuff... (1)

Viol8 (599362) | more than 4 years ago | (#30117054)

... learn COBOL. Nice and long winded and "englishy". And an utter PITA.

Forced to use Bad API (2, Insightful)

Baby Duck (176251) | more than 4 years ago | (#30117088)

If I have a long comment explaining "magic", 99 times out of 100 it's because I'm being forced to interface with a bad API which THAT CODER didn't properly understand. Glaring errors in the documentation, unexpected outputs, unexpected hangups ... these are my duty to comment about. Of course I don't understand why the API is malfunctioning ... it's a BLACK BOX. My employer might be too much of a cheapskate to purchase product support to troubleshoot the API. Or the vendor might charge outrageous support fees for their mess ups. I cannot switch to a different API, because I do not have the authority to make that decision. My comments are self-defense when backed up against the wall. It does nothing to gauge my programming ability.

You are not expected to understand this (4, Funny)

wandazulu (265281) | more than 4 years ago | (#30117090)

The granddaddy of WTF comments must come from the original Unix source, written by none other than Dennis Ritchie: /*
          * If the new process paused because it was
          * swapped out, set the stack level to the last call
          * to savu(u_ssav). This means that the return
          * which is executed immediately after the call to aretu
          * actually returns from the last routine which did
          * the savu.
          *
          * You are not expected to understand this.
          */
        if(rp->p_flag&SSWAP) {
                rp->p_flag =& ~SSWAP;
                aretu(u.u_ssav);
        }

So here's an example of a comment that does an excellent (I assume) job of explaining why the code is doing what it's doing, yet the whole thing is so complicated that Ritchie even needed to acknowledge that the comment probably wasn't going to be of much help either with an amusing, and now somewhat famous, statement.

An addition (2, Informative)

wandazulu (265281) | more than 4 years ago | (#30117128)

Dennis Ritchie has a whole page of comments [bell-labs.com] in the Unix source code, and what information they convey.

OT on long comments (5, Interesting)

FrankSchwab (675585) | more than 4 years ago | (#30117144)

Being as this is devolving into a discussion of long comments, rather than a discussion of whether mispellings in comments indicate a lack of attention to detail in coding, I thought I'd throw in something.

To maintain some sense of topicality: I don't particularly agree with the blog post. As someone with good English skills, I've read a lot of code where the English language skills (and thus spelling and grammar in the comments) of the coder are below mine, but their skills in the computer language at issue are superior to mine. Frankly, there's a far greater relationship between accuracy of the comments (do they actually describe what the code does) and the quality of the code, than there is between spelling, subject-verb agreement, and number of spaces after a period and the quality of the code. This relationship does follow the blog author's contention about coders needing to be nit-pickers.

Occasionally in my coding, I write a novel in the function header. Generally, this isn't because I don't understand the problem so much as its because I do understand the problem. I've spent hours or days understanding the problem, and the particular necessray function that implements the solution, and I don't relish spending hours or days 6 months in the future remembering what I know today. The interesting thing is that, most of the time, the novel is multiple times larger than the function - 50 lines of comment for a 20 NCLOC function isn't unheard of.

In my specialty (embedded systems, with especially tight hardware integration), there are functions that need to be written that deal with extraordinarily complex situations. Many times, the bare code tells a misleadingly simple tale - "do this, that, and the other thing", rather than (as Russ Nelson pointed out above)

but to explain all the other code that could have been written, but wasn't

. Oftentimes, the novel is there to explain all the ways to trip up in this 20-line function - e.g. unspecified hardware dependencies, subtle system dependencies, unobvious race conditions. Sometimes its there to explain why, no matter how wrong the function appears, it is actually correct.

Native English Speaker (1)

binaryartist (1172973) | more than 4 years ago | (#30117152)

What if the person who wrote grammatically incorrect comments is not a native English speaker? Engligh not fluent, C++ very fluent!
Load More Comments
Slashdot Account

Need an Account?

Forgot your password?

Don't worry, we never post anything without your permission.

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>
Create a Slashdot Account

Loading...