[huggyface]

After the recent discussion about code-comments, that sort of code is exactly the sort that requires an explanatory comment.

If the code isn't the clearest comment you have, you're doing it wrong.

Comments are a crutch for people who write poor code. Comments have zero authority or guarantee of accuracy, and more often than not have little correlation with the actual code.

Code is canonical. Comments are noise.

[joshhart]

I think you're wrong for one simple reason: business logic.

Business logic is complicated and rarely defined by a developer but by a product manager. Often you can understand what's being done in the code, but the WHY is necessary to understand why it's there and what it is trying to do. I believe giving a brief synopsis of the business logic in a method comment and, if it's not super straightforward, a brief overview of the steps or algorithm, is incredibly useful.

I guarantee you won't be able to figure out what your program is doing by looking through years old wikis left by product managers no longer at your company.

[huggyface]

Just to be clear, the person I responded said, in effect, that the code did X. They made code that did Y, and then realized it didn't do X. That is the story of a million ill conceived code rewrites.

That the code did X is clear by the code: No amount of words can refute or change that the code does X. The danger is replacing code is always in the behavior of the code, and never simplified descriptions of its actions.

To business logic, as someone who has worked heavily with business code for years (laughable commentary from imbeciles to the contrary), business logic in comments is one of the worst choices a team can make because it is an escape hatch. It negates the need for verbose, traceable code. It negates the need for vastly superior external proof.

[eru]

Mathematicians have much more convenient symbols and powerful notation than programmers. Yet they use text, too. Even wondered why?

Donald Knuth, who gives money to people who spot bugs in his code, even invented literate programming to mix prose explanation and code better. Is he an idiot?

[huggyface]

I'll happily be "so brave" and reiterate a simple truism of software development -- comments are the battle cry of terrible developers.

They are the crutch of people who can't read code: "Add more comments because otherwise I can't make sense of what the statements are doing." It is the English speaker demanding that every French passage have an English translation, rather than simply learning French.

They are the crutch of people who can't write code. "My code is a gigantic, illiterate mess, so instead read the comment at the top that has no guarantee of being robust or accurate."

Bringing up mathematicians and Knuth are both irrelevant distractions. Software development in the modern world is a very structure, self-describing affair, or at least it should be. Comments are the short-circuit from having to figure out how to do that.

[run4yourlives]

I'm not meaning to insult you, but you sounds like a programmer who's experience consists solely of personal projects and academic assignments.

As has been said, comments explain why you are doing something in a certain way. That why is often related to a business process, several business process, and/or 25 different outside cases.

The code can be amazingly clean and organized, but you comment to indicate why you did something one way and not another.

[huggyface]

I'm not meaning to insult you

Sure you are. And that's okay.

[FuzzyDunlop]

I'd like you to offer some examples of code that successfully documents its own raison d'être - in a way that a comment couldn't do better - instead of repeating this 'crutch of poor developers' rhetoric.

I mean, I can write self documenting code without any comments, and it's perfectly understandable.

    before_create :auto_increment

    def auto_increment
      self.count + 1
    end

That code fails to tell the programmer why it's in the application logic and not defined in the database schema. What should I do instead, so I can code without crutches?

    def auto_increment_natural_key
        self.count + 1
    end

That's not a great deal better, it's still just saying what it does, not why it's there in the first place.

    def auto_increment_natural_key_because_another_app_relies_on_it
        self.count + 1
    end

Is that it?

[randomdata]

Your code doesn't actually seem to do anything, so a comment would either be contradictory to the code, which is confusing, or explain why your code does nothing, which is silly.

I would argue that in this case, it is far better to just understand the code and then fix it appropriately. A comment would leave you second guessing.

    def auto_increment
      self.count += 1
    end

(though, for the purposes of self documenting code, count probably is not a great variable name either)

[FuzzyDunlop]

Rather ironically, it appears my poor choice of example could have done with some more documentation.

[randomdata]

I'm now curious to know what you would have written for documentation.

Though, I think your example turned out to be a great one because it highlights that not everyone reads code the same way. Personally, I load large segments of code into memory and then mentally step through. You left me wanting more to see the context in which the method was to be executed, but I didn't really feel the need for comments.

However, with just the one method that you wrote in your example, that seems to indicate that you read just one function at a time. If you are not observing the code as whole, I guess a comment would help. I often find them taxing though, as they have to be read into memory as well.

I think that discrepancy is why the comments vs. self-documenting code debate exists.

[eru]

Thanks for trying!

Now we just put the comment in the variable name. The compiler just checks the variable names all match up, but doesn't check whether their names make sense.

Perhaps the example chosen was too much of a toy to yield valuable insight?

[huggyface]

That code fails to tell the programmer why it's in the application logic and not defined in the database schema

Why isn't it a GUID? Why is it 32 bits instead of 64? Why is it signed yet starts at 1? Why isn't it a string? How will the identities be merged?

The notion that answering one single question provides clarity is ridiculous.

[run4yourlives]

def auto_increment_natural_key_here_because_if_a_product_doesnt_have_a_key_assigned_because_it_came_back_from_return_and_wasnt_assigned_on_during_the_recieve_shipment_process_the_key_doesnt_exist_and_another_app_relies_on_it

Pretty sure that's it.

[rhizome]

Your sarcasm is screwing with HN's page formatting.

[dredmorbius]

This is what element inspectors/editors are for. Snip, snip.

[ballooney]

Your hubris is certainly self-documenting, if it gives you any comfort.

[ChuckMcM]

He (or she) is just early on the path, and like a newborn kitten their eyes are still closed. In the mean time keep them away from pointy things.

[huggyface]

I hope that caricature gives you some comfort in your utter mediocrity.

[huggyface]

What a useful contribution.

[vadman]

Do you have github/sourceforge? I'd love to read some of your non-trivial code.

I'm not trying to be an a$$hole btw. I am not a coding guru, I genuinely want to minimize the need for comments in my code and am willing to learn from examples.

[huggyface]

Do you have github/sourceforge? I'd love to read some of your non-trivial code.

Read almost any non-trivial successful project for good examples. The Linux kernel. Firefox. etc. The frequency and verbosity of comments tends to have a direct correlation with the simplicity of the code (which is the exact opposite of normal expectations).

[flatline3]

Linux and Firefox code basis are messes.

Have you written any large projects that you've had to maintain over years, or worked with large teams, or handed off maintenance of a large project to others?

[huggyface]

Two projects that are enormous successes, both with more contributors than any code that you've ever touched, I would wager. "Messes". Indeed.

To your questions, while you're rhetorically asking, trying to wink to the crowd in the implication that the answers are telling, yes, actually I have. To very good effect. I'm speaking from actual experience here, not just the hilarious patter of the bottomfeeder that is far too typical on HN.

[eru]

Making the machine check as much as possible about your code is a worthy and practical goal. I often try long and hard to capture as many invariants as possible in the type system. And even though the language that we are using, Haskell, has one of the strongest typesystems you can find, that's still not very much logic guaranteed by the compiler. Of course, run time checks can catch a few more errors, but I'd rather catch mistakes as early as possible.

You seem to have lots of experience with expressing intent in code, and making that intent 'canonical'. How do you make the machine check the accuracy of your code? What language are you using for that?

[wtetzner]

You seem to be missing the point of comments. Comments are not meant to explain what your code does. They are for explaining why.