1. 17
  1.  

  2. 12

    I’ve always kind of thought “good code is self-documenting” is a useless tautology. Good or bad, the code always says exactly what it’s going to do, by definition. If a person knows the language, they can always figure out what the code is doing by reading it carefully enough. I agree with the underlying idea that good naming is important, but I think it’s clearer to just say that.

    But no amount of good coding practices can explain why it’s written the way it is, and that’s almost always what I really want to know. The best way to do that is with comments and good discipline keeping them up to date.

    1. 3

      Good or bad, the code always says exactly what it’s going to do, by definition.

      There are multiple ways to say the same thing and some of those ways are easier to be understood than others. The laws of physics are inherent in the physical universe. But you don’t drop an engine on a child and say “well the device is going to do what it’s going to do, by definition. If you exist in a physical universe and can thus interact with this device, you can always figure out what the device is doing”.

      1. 2

        There are multiple ways to say the same thing and some of those ways are easier to be understood than others.

        Of course, but being easy to understand isn’t the only criteria, and it’s usually not the most important criteria. It may be important to know whether the original author wrote the code this way because it’s the first thing that came to mind, because it’s the easiest to understand, because it’s the fastest, because it’s what the stakeholders requested, etc..

        In other words, if there are multiple ways to say the same thing, why did the author choose this particular way of saying it? If it’s important, it’s nice to have a comment saying so.

        The laws of physics are inherent in the physical universe. But you don’t drop an engine on a child and say “well the device is going to do what it’s going to do, by definition. If you exist in a physical universe and can thus interact with this device, you can always figure out what the device is doing”.

        Sure, but but nobody (as far as I know) is claiming that a good engine should be self-documenting.

      2. 2

        Comments can also save time. Instead of having to read ten thousand of lines of code to understand the bigger picture, design, etc, a good comment can just do that for me. Same if there is anything else that cannot be understood quickly/easily just by reading the code, or if some interesting finding or “Aha moment” about the code should be communicated, comments are also a good place. And generally speaking, a good part of all design discussions and code justifications that appear in long commits messages and pull request threads would be more valuable in the code itself.

      3. 4

        GHC has a pretty good system for this, where they use the concept of a Note which is a short link to a longer comment in the same or a different file. e.g.

        tcTyClGroup :: TyClGroup GhcRn
                    -> TcM (TcGblEnv, [InstInfo GhcRn], [DerivInfo])
        -- Typecheck one strongly-connected component of type, class, and instance decls
        -- See Note [TyClGroups and dependency analysis] in GHC.Hs.Decls
        tcTyClGroup (TyClGroup { group_tyclds = tyclds
        ...
        

        And this is used to justify any particular decision that has been taken.

        1. 3

          Code and commits last. Source code management systems expire.

          Perhaps some of this is a place for a very good set of paragraphs in the commit message.

          1. 3

            I have never been able to do a good job with commit messages. I appreciate groups that force commits to follow an exact pattern and use them to describe the pull request.

            I’d like to improve on this. Still, with squashed commits you lose information.

            1. 6

              Still, with squashed commits you lose information.

              It’s the person who is squashing the commits responsibility to re-construct the commit messages into an uber cohesive message with all the same detail. It’s a very good reason to ask the pull request author to squash their own commits before merging, and the reviewer can then validate the resulting commit message before merging.

              1. 2

                Uh, but why squash the commits, instead of keeping them separate, and thus ideally understandable in small pieces? Personally, before opening a PR, I typically do a lot rebasing and massaging to make the history as easy to review and understand as possible; I’m not sure what value would be then in squashing it into a single uber commit?