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.

  • Zacryon@feddit.org
    2·
    5 hours ago

    I don’t like code, that isn’t well documented. In fact, this has been my main source of frustration in the past and required the most time to deal with. Thousands of variables, hundreds of thousands of lines of code, how am I supposed to go through it somewhat fast, if there aren’t any comments or pieces of documentation that are guiding my understanding? I can’t spend half a year to just get a grasp of how the code works.

    Comments (as well as docstrings and readmes etc.) provide higher level overviews that can guide you through the code rather quickly, even if it may be longer in terms of words or character count than the lines of code it describes, it may accelerate understanding tremendously. It’s just a lot more effort to trace each variable and see what it does and how it interacts with others. This can quickly become exponentially hard to track.

    I don’t think it’s necessary to comment each line of code, except in rare cases or maybe when setting up a class and describing the members and roughly how they’re used, but a few words here and there, at some higher or intermediate level, roughly describing what you want to do, can go a long way for others (and even yourself, when working on a project for several years). It’s also already sufficient to just highlight the most important variables in a piece of code, when explaining it. Given that info, this steers your focus when reading the actual code.

    “Speaking” variable/function/… names are also very useful. I don’t care if it’s a long name, as long as it’s sufficiently expressive. E.g. “space_info” instead of “si”. This helps to understand the code more quickly and reduces backtracking lookups, because you already forgot again what a specific variable does that you haven’t seen for a while. My rule of thumb for variable naming: As consice, short and “essence grasping” as possible, but as long as necessary.