Here’s a belief I’ve held for a while but only recently been able to put into words: explanatory comments are often easier to understand than explanatory variable or function names. Consider a complicated expression with multiple sub-expressions. This expression is going to be difficult for the next person reading this code to decipher; we should make it easier for them. There are a couple of ways to solve this. We could break down the expression into sub-expressions, and assign those sub-expressions to intermediate variables. Or we could pull the expression out into its own dedicated function. In each case, the goal is to give either part or all of the expression a dedicated name. This name helps the next reader to understand the purpose or meaning of the expression.

Thoughts? It does feel like there’s a lot of things you can do in comments that would be impossible or impractical to do in names alone, even outside of using comments as documentation. There’s certainly much more information that you can comfortably fit into a comment compared to a name.

One of the comments in the Lobste.rs post that I got this from stuck out to me in particular:

Funny story: the other day I found an old zip among my backups that contained the source code of game that I wrote 23 years ago. I was just learning to code at the time. For some reason that I forgot, I decided to comment almost every single line of that game. There are comments everywhere, even for the most obvious things. Later on, I learned that an excess of comments is actually not considered a good practice. I learned that comments might be a code smell indicating that the code is not very clear. Good code should be so clear, that it doesn’t need comments. So I started to do my best to write clear code and I mostly stopped writing comments. Doing so only for the very few parts that were cryptic or hacky or had a very weird reason for being there.

But then I found this old code full of comments. And I thought it was wonderful. It was so easy to read, so easy to understand. Then I contrasted this with my current hobby project, which I write on an off. I had abandoned it for quite some months and I was struggling to understand my own code. I’ve done my best to write clear code, but I wish I had written more comments.

And this is even worse at work, where I have to spend a ton of time reading code that others wrote. I’m sure the authors did their best to write clear code, but I often find myself scratching my head. I cherish the moment when I find some piece of code with comments explaining things. Why they did certain things, how their high level algorithm works, what does this variable do, why I’m not supposed to make that change that looks like it will simplify things but it will break a corner case.

So, I’m starting to think that this idea that comments are not such a good practice is actually quite bad. I don’t think I can remember ever reading some code and thinking “argh so many comments! so noisy” But, on the other hand, I do find myself often in the situation where I don’t understand things and I wish there were some more comments. Now I’m trying to write comments more liberally, and I think you should do the same.

I guess that’s a generalization of the op’s idea.

  • squaresinger@lemmy.world
    4·
    10 hours ago

    Tbh, creating new code just to shorten variable names is pretty bad practice. Don’t do that.

    Each line of code needs to be maintained, each line of code can contain bugs and reusing such a class in locations it wasn’t actually made for can cause more harm than good.

    And if you are adding external information (e.g. via a class) why not just add that information as inline documentation (aka comments) instead? Most IDEs can handle that so that if you hover over the variable/function name it will display the documentation. And pretty much all IDEs allow you to navigate to declaration with just one click, and there you find the necessary information.

    You example only gets worse if you keep nesting these things, so for example if I have:

    int sleepIntervalSeconds = 0;

    Then I immediately know:

    • It’s an int (not a double)
    • It’s an interval used for sleeping
    • It’s in seconds

    (Putting all that in a comment instead of the variable name is almost equally as visible via IDE)

    Instead consider your proposal, which would read like this:

    Intervals var.sleep = 0;

    I used var as the variable name since you abstracted the informations “sleep”, “interval” and “seconds” into other definitions.

    So now I still know it’s an interval used for sleeping, but both the real variable type and the information that it’s in seconds is gone. I have to navigate to the Intervals class/type to figure that out.

    IRL this often gets even worse, because Intervals probably doesn’t even contain the fields directly, but instead inherits from a Time class, which then inherits from some other class, and then you might get to the actual definition of the field.

    This is only amplified by using Mixins and other obfuscation goodness.

    If you have two options, and one option creates extra code, extra classes and extra code paths without reducing the complexity of the code significantly, than that’s the worse option.

    • towerful@programming.dev
      2·
      7 hours ago

      Yeh, my example was pretty contrived and very surface level.
      It grouped things that seemed related at a surface level but weren’t actually related at all. Which makes it a bad example.
      And realistically, you would use a timer class that raised events, and passed in an interval class that could be constructed from any appropriate units.

      It was more to highlight that types and classes are a fairly easy way to improve the context around variable.
      It can also use type checker to show incorrect conversions between minutes and seconds, Polar and Cartesian coords, RGB and HSV, or miles and kilometers. Any number of scenarios where unit conversions aren’t a syntax error.

      • squaresinger@lemmy.world
        2·
        6 hours ago

        I know it was just an example, and examples are always contrived. It was just a good example to show how complexity can increase a lot if you use classes/types as glorified comments.

        This total denial of the existence of comments, which is a common attitude right now, can easily do more harm than good, when you add code not for functionality but instead just to have more space for symbol names to put text into.

        The project I worked on in my last job suffered a lot from this. It would lead to some really weird patterns, like e.g. this:

        class BaseCommand {
    var commandType
}

class CreateCommand extends BaseCommand {
    public CreateCommand() {
        this.commandType = CREATE;
    }
}

        We had dozens and dozens of classes that didn’t actually contain any actual code, but were just flavour for “readability”, which in turn just created garbage lines of code and all that trash would negate any potential benefits to readability. And since the code was spread out over so many classes it would mean that even simple changes would require touching tons of files.

        I had, for example, a very simple 1 Story Point task to do. The whole task was “rename a variable”, nothing more than that. I had to change 40 files. Not an exaggeration, it really was 40 files.

        Code is for code, comments and external documentation are for documentation. Don’t abuse one for the other.