Slashdot Mirror

← Back to Stories (view on slashdot.org)

If the Comments Are Ugly, the Code Is Ugly

Posted by CmdrTaco on from the what's-wrong-with-minimalism dept.

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.'"

28 of 660 comments (clear)

  1. The comment may also be complex.. by Oxford_Comma_Lover · · Score: 5, Insightful

    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.

    --
    -- IANAL, this isn't legal advice, and definitely isn't legal advice for you. Also, Squee!
    1. Re:The comment may also be complex.. by Anonymous Coward · · Score: 5, Insightful

      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 ...

    2. Re:The comment may also be complex.. by gstoddart · · Score: 4, Insightful

      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

      --
      Lost at C:>. Found at C.
    3. Re:The comment may also be complex.. by Abcd1234 · · Score: 5, Insightful

      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*.

    4. Re:The comment may also be complex.. by Anonymous Coward · · Score: 3, Insightful

      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.

    5. Re:The comment may also be complex.. by Esther+Schindler · · Score: 3, Insightful

      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.

    6. Re:The comment may also be complex.. by Kell+Bengal · · Score: 5, Insightful

      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.

      --
      Scientists point out problems, engineers fix them
      altslashdot.org: The future of slashdot.
    7. Re:The comment may also be complex.. by Abcd1234 · · Score: 5, Insightful

      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.

    8. Re:The comment may also be complex.. by Abcd1234 · · Score: 4, Insightful

      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?

    9. Re:The comment may also be complex.. by YXdr · · Score: 5, Insightful

      ... 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.

    10. Re:The comment may also be complex.. by Unequivocal · · Score: 4, Insightful

      And while "he" is getting called at three in morning 2 years later to fix a crazy bug that has stopped all business, due to a new use-case being introduced that mysteriously breaks that function, "you" is now coding on a new project, using sound development techniques (including understanding how code works while "you" writes it), making the company new money.

    11. Re:The comment may also be complex.. by Abcd1234 · · Score: 5, Insightful

      Construction, even of your vaunted bridges is filled with hacks carried out at all levels of the build.

      Oh please. Inexactitude is *not* the same thing as not understanding why something works at all. We can build miles-long bridges *specifically* because we understand the underlying physics, and anyone who built a bridge without understanding the physics of why it stood under load would be drummed out of the industry.

      Software development typically isn't engineering. It's usually a business of maximizing productive features versus minimizing cost and time. Rarely is the answer to further investigate working code.

      Sorry, that's crap. Any code complex enough to be difficult to understand is specifically the code that requires extra care and attention to ensure it's correct. If you don't understand why your complex algorithm works, you need to spend more time to understand it, as the odds are extremely good that it's a) not correct, and b) not maintainable.

    12. Re:The comment may also be complex.. by Senjutsu · · Score: 4, Insightful

      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).

      Coding two routines by coincidence is not more productive than coding one routine properly.

    13. Re:The comment may also be complex.. by TheRaven64 · · Score: 4, Insightful

      And then, when someone comes up with a corner case where his code doesn't work, how much more time is he going to spend finding and then fixing the bug? And how much will his company's reputation suffer while his customers experience the bug?

      --
      I am TheRaven on Soylent News
    14. Re:The comment may also be complex.. by Dragoness+Eclectic · · Score: 5, Insightful

      I've had to maintain code originally written by people with that attitude. To put it politely, I wish they'd switched careers to something besides computer programming; it would have saved everyone a lot of work, cost overruns, budget overruns, and pissed off a lot fewer customers.

      If you don't know what the hell you're doing, you're not going to do it very well. Code that "works by accident" is very fragile and breaks easily and is a triple bitch to maintain, because if you don't know what you wrote, I have to pretty much reverse engineer it from the source code to figure out what you *actually* wrote vs. what you were supposed to write--then I usually end up re-writing it from the original requirements to do what it should have been doing in the first place, because the existing code is such a mess.

      --
      ---dragoness
    15. Re:The comment may also be complex.. by Seraphim1982 · · Score: 5, Insightful

      The reason the 2000 year old Roman bridges survive is because all the shitty ones were destroyed hundreds of years ago.

  2. Comments are good by Anonymous Coward · · Score: 5, Insightful

    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. :-)

    1. Re:Comments are good by e70838 · · Score: 5, Insightful

      Comments shall be avoided as much as possible :
      1) the code shall be simple and the name of variables and methods shall be self explanatory in most cases. When this is applied, there remains very few to explain at the code level. The reader of your code is not dumber than you (except when he is your boss).
      2) the more you add comment lines, the less lines of code you can see on your screen. When you start scrolling continously, the speed of code production reduces significantly.
      3) comments introduce a redundancy. What shall be trusted when code and comment differs. Is the code wrong or the comment outdated ?
      4) comments in the code are often used as a substitute for a global software architecture description. In the example of the java api documentation, it is very hard to get a global view of a class with only class comments, we need additional documentation (the tutorials).
      Joke apart, code often contains many comments because it shall comply to quality standards, but strangely, the parts of the code that are difficult to understand are generally not commented. It is a variant of Murphy law that is very useful when auditing code.

    2. Re:Comments are good by clone53421 · · Score: 4, Insightful

      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.

      *rolls eyes*

      I, on the other hand, think it would be valuable to know if and when the person writing the original code *THINKS* the code does something which, in fact, it does not.

      --
      Alexander Peter Kristopeit bought his basement from his mommy for one dollar.
  3. Co-workers by Tomun · · Score: 5, Insightful

    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.

    1. Re:Co-workers by garcia · · Score: 5, Insightful

      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.

  4. comments explain what isn't there by Russ+Nelson · · Score: 3, Insightful

    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.

    --
    Don't piss off The Angry Economist
  5. bad spelling in variables/etc get me by i.r.id10t · · Score: 3, Insightful

    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.

    --
    Don't blame me, I voted for Kodos
  6. Long-winded comments can be very useful by JoshuaZ · · Score: 5, Insightful

    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.

  7. Non-native English speakers by AmiMoJo · · Score: 4, Insightful

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

    --
    const int one = 65536; (Silvermoon, Texture.cs)
    SJW, n: "Someone I don't like, and by the way I'm a fuckwit" - AC
  8. Yes, that's bad coding by Frequency+Domain · · Score: 5, Insightful

    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.

  9. Re:Blame Game by Abcd1234 · · Score: 5, Insightful

    Nowhere in "faster and cheaper" is there room for your mythic "formalized discipline."

    Wait... suddenly understanding your own code is "formalized discipline"? Might I suggest your standards are simply too low? Because, in my mind, understanding your own code is in the category of "basic competency".

  10. syntactic and logical perfection can be crap by lophophore · · Score: 4, Insightful

    Perfectly working, syntactically and logically correct code can be utter crap if it is not maintainable.

    Years ago, a very smart man told me that I was not writing code for the compiler, I was writing code for the next poor slob that had to work on it. Let's face it, most source code is going to be subject to rework or maintenance over its life span, so let's do what we can to make that next developer productive. The key to this is reasonable commenting.

    One of the best ways I know of to teach developers to write maintainable code is to have them do support and maintenance for a while. Developers learn quickly which styles work for maintenance, and which ones don't.

    As far as I am concerned, source code needs to look good as well as compile. So I would go one step beyond TFA to say that style, indentation, proper symbol names, use of constants where appropriate, and (yes) proper commenting are all good indicators of quality in source code.

    --
    there are 3 kinds of people:
    * those who can count
    * those who can't