This Overly Long Variable Name Could Have Been a Comment | Jonathan's Blog
-
Symbol names can be outdated as well, but what's worse is they can be flat-out wrong.
Real-life example that I had at my last job:
var isNotX = isX() // somewhere else in the code: var isX = isX() fun isX() { // Code returns isNotX }That part of the code had a bug and it wasn't clear whether the function should return X or not X (the function was much more complex but returned a boolean).
A comment could have given context and/or be used as parity check for which implementation would have been correct.
This way I had to step through the whole flow just to figure out what it's doing and what it's supposed to do.
Everything comes down to proper function naming. If it wasn't clear what function should return, then it was not named properly.
-
I try to write comments whenever what the code isn't obvious on its own. A "never write comments" proponent might argue that you should never write code that isn't obvious on its own, but that doesn't always work in practice
- Sometimes you have to write cryptic code for performance reasons
- Sometimes you have to deal with unintuitive edge cases
- Sometimes you have to work around bugs in 3rd party code
- Sometimes you are dealing with a problem that is inherently complex or unintuitive, no matter how you put it in to code
Sometimes you just need to document the business reason behind what you're doing, regardless of how clear the code might be
-
More people should try out literate programming. It is very powerful, especially for complex code and software you want to maintain in the long run.
Literate programming as an ideal works at very very high level and very very low level. Plumbing code often doesn't benefit from comments at all, and is the usually the most subject to refactoring. Code by amateurs/neophytes is often not gonna be written in such a way that a clear description of the intention or mechanics is achievable by the coder. Unobtainable standard, smh. I like comments with a 'why' at the top and a 'what' at the bottom (of the stack. I'm talking about abstraction layers. Why am I doing this piece of logic in the code you can clearly understand at the top, what the fuck am I doing these weird shenanigans with a fucking red-black tree of all things in this low level generic function)
-
The biggest problem with comments is that they can become outdated. If you change code but forget to change comment you introduce very dangerous situation where they become not only not useful, but also misleading.
If you rely on variable names, you've got a single source of truth, one thing to change at a time. Information updates itself.
People always say this, and I have seen it happen occasionally. But in practice when it happens it's usually fairly obvious and not that confusing (especially with
git blame).The frustration I've experienced from missing comments is several orders of magnitude more than the frustration I've experienced from outdated comments. I think mostly this is an excuse to be lazy and not write comments at all.
-
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.
My philosophy is that anyone familiar with the code shouldn't need the comments to understand it, and anyone who isn't should be able to with the comments.
This means that I have semi long names like "this_variable_varies" would be about the max name size I would use. But I also use plenty of small functions and I use comments to explain big chunks of code with just a simple goal and method description.
I sometimes find my code a bit overly verbose, but I know I would rather see that then some code that I need to de-obfuscate mentally.
-
Later on, I learned that an excess of comments is actually not considered a good practice.
Pointless or uninformative comments are not good, regardless of the quantity.
Useful and informative comments are always good, regardless of the quantity.
I learned that comments might be a code smell indicating that the code is not very clear.
When I'm looking at someone else's code, I want to see extensive, descriptive comments.
Good code should be so clear, that it doesnāt need comments.
That hits me like something a teacher tells you in a coding class that turns out to be nonsense when you get to the real world.
I'm not sure how others do it.
As I'm coding, the comments form part of my plan. I write the comments before the code. As I discover I've made incorrect assumptions or poor decisions, I correct the comments with the new plan, then correct the code to match the updated comments.
As a final step in coding, when I feel it is complete, I'll review comments to determine what should remain to help future me if I ever have to dig into it again.
Variable names should be reasonably memorable and make contextual sense, but that's it. That's what they exist for. Don't overload the purpose of anything I'm the code.
I also do this with comments. But usually, the comments become my function names, and then the comments are redundant.
-
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.
I like both comments and long variable / function names. I also like it when people break functions down into excessively fine detail.
Why? Because deleting redundant lines is always easier than figuring out what is going on when you don't have the information you need.
I will name functions by just vomiting out my current train of thought about what the function needs to do. Sometimes it ends up being so long it runs off the page. Good. Now I know exactly what the function does, and anyone in the future will too. But more importantly, an obnoxiously long name draws the ire of everyone who reads it until someone comes up with a better name - usually me, when I'm not actively trying to write the code in the function body. As long as this isn't a public function in a library that is actively being referenced by hundreds of people, the change is easy with modern ide refactoring tools.
-
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.
No short variable names, also no non-lewd variable names, life is nothing without suffering.
-
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.
Clear concise code that reads like documentation is the ideal. Good function and variable names, formatting, and encapsulation play into this. Tests should document and describe the system.
If it still isn't clear what the code is doing, and I'm all out of ideas (or time) for refactoring, a well placed, accurate comment is fine. It needs to be kept up to date like any other artifact in the project.
It's harder to keep comments accurate than code, since code can be executed and tested. I use them sparingly; when I've otherwise failed to write clean code, or the code is just so complex that it needs to be described.
Comments are just another tool in the toolbox. If they add clarity to the situation, by all means, use them.
If you can think of an expressive variable name that lets you skip a comment eg "employeeCount", instead of "e" // number of employees, do that.
-
Sometimes you just need to document the business reason behind what you're doing, regardless of how clear the code might be
//look, I know this makes no fucking sense, but Debbie at MoronCo insisted it worked like this or she wouldn't pay us -
The biggest problem with comments is that they can become outdated. If you change code but forget to change comment you introduce very dangerous situation where they become not only not useful, but also misleading.
If you rely on variable names, you've got a single source of truth, one thing to change at a time. Information updates itself.
The same thing can be true about variable names, and it is often more time consuming and error prone to change a variable name to match its new meaning than to simply update a comment. Especially if the variable name is public facing through an API or library then there is a huge cost to change the name everywhere that might reference it.
