1. 2

  2. 3

    The article doesn’t answer the question, so it’s kind clickbait-y, but the discussion is reasonable, although not breaking any new ground.

    The best it offers is a heuristic.

    I offer the heuristic that the correct way to comment is to avoid them as much as humanly possible.

    Meh. Maybe. It’s not compelling, but neither is it repulsive.

    Unfortunately, it seems that knowing when to add comments can only be determined after leaving the code for a few weeks. If you come back and don’t understand it, you probably need some comments.

    1. 2

      If you come back and don’t understand it, you probably need some comments.

      Unfortunately, by then you probably need to have already written the comments a few weeks earlier. And this is the key problem with the “if it’s easy to understand you don’t need to comment it” argument: the person who’s deciding whether it’s easy to understand has just dug into the problem enough to write a solution to it, therefore finding it easier to understand than anybody who hasn’t done that.

      1. 1

        That was kind of my point: you don’t know until it’s too late.

      2. 1

        If you come back and don’t understand it, you probably need some comments.

        Or, more likely, a refactoring to make the code readable ;)

      3. 2

        Don’t comment unless you need to, in which case do comment. I feel enlightened now.

        1. 0

          Woah, way to blow my fucking mind dude.

        2. 1

          I’m not really a fan of this article. The entire thing is spent talking about heuristics, but hardly ever touches on the actual thing you care about. This is all I could find:

          Comments have an obvious purpose: communication and clarity.

          Comments are a tool to solve a particular problem, and that problem is communicating ideas to other humans. (Which in turn is motivated by another goal, which is that one presumably wants others to use the things they build.) I try to model my heuristic on that. Who is my target audience? Can I put myself in their shoes and try to guess at what they might want to know? What details aren’t obvious from the name itself? Or, what invariants aren’t expressed in the type system? If you’re trying to communicate something to someone else, then you have to figure out how to do it in a way that they can understand it. This is an inherently messy process, and I think a lot of it depends on the target audience.

          Here are some target audiences that I’ve written for inside comments:

          1. End users that know nothing about code, but want to make use of the software.
          2. Users of a particular library that know nothing about specific implementation details, but do want to know how to use the API.
          3. Programmers looking to modify the internals of a library.

          My opinion is that heuristics like (to summarize the OP) “try not to comment” aren’t that useful, because that just winds up being a more specific form of write for your target audience. That is, when do you know when a comment is or isn’t appropriate? Well, you have to make a judgment call on whether the code speaks for itself. How do you know that’s true? Well, you need to come up with a mental model of what other people are capable of understanding from just the code you’ve written, and if you think it’s enough, then maybe you don’t need to write any comments.

          With all that said, I do agree with pointing out the trade offs of writing comments. We don’t always have all the time to write comments, and some might consider undocumented code better than no code at all, depending on the situation. I’ve certainly found myself in that situation.

          The other tradeoff—that comments can be wrong—isn’t that compelling to me. Lots of things can be wrong, including the code itself. Should we just avoid the problem of being wrong by not doing anything at all? No. Just treat wrong comments as a bug to be fixed.