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

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

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

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

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

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

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

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

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