Threads for MorganGeek

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

      1. 16

        I’m using zola, and I think it’s brilliant!

        Ticks the boxes for all your desires. It’s fast, contained in a single binary, has a live updating local server, documentation is good and allows extra custom configuration properties for custom things in themes.

        My personal website is built using Zola, here’s it’s source.

        1. 3

          I think this is the one! Thanks!

          1. 3

            I’ve been testing zola right now, in particular the sam theme, against a lot of website analyzers (accessibility, performance, w3c validators, ecological impact,..) and it’s pretty good, I think I’m gonna start using it, it looks simple and mature while providing all the features I wish (code formatting, RSS, …).

            1. 1

              Exactly! And it’s easy to modify, and somewhat extensible for additional features you might want.

            2. 2

              I use Zola as well. I think one of the biggest downsides is how few themes there are. In principle it’s not much work to modify an existing theme, but it’s still one more thing you need to do when setting up your blog.

              1. 1

                You’re right. I wanted to build a custom theme anyway to personalize things, so that wasn’t much of a problem for me.