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.
One big reason for requiring comments being updates the same time as what is commented. I once managed to do that for a while when I alone was making and maintaining a project.
It becomes harder, the more people are working on a project and the larger the project gets.
But the alternative would lead to Java-like function-etc names and that is not very desirable either.
I feel like variable or function names that become overly verbose indicate that a specific type or a separate class should be considered.
I see it as a mild code smell.
Something like
int intervalSeconds = 5could maybe have a type that extends an int calledseconds. So then you are declaringseconds Interval = 5.It describes the unit, so the variable name just describes the purpose.
You could even add methods for
fromMinutesetc. to reduce a bunch of (obvious) magic numbers elsewhere.To extend this contrived example further, perhaps there are a couple of intervals. A refresh, a timeout and a sleep interval.
Instead of having.
You could create an intervals class/object/whatever.
So then you have.
The class/object defines the context, the type defines the unit, and you get nice variable names describing the purpose.
But this can lead to over engineering simple stuff. Which makes the code harder to read and maintain and more error prone. Especially if you don't need all the other stuff for the class. Worse, if you define a class then you also tend to add more stuff you don't use, just in case it might be useful.
A simple variable name is sometimes the better solution. But it depends on the situation off course. Sometimes a new class make things more clear, as it abstracts some complexity away. Yeah, we need to find a balance and that is different for every program.
This depends. Many languages support 1 liner aliases, whether that's
using/typedefin C++,typein Rust, Python, and TS, etc.In other languages, it may be more difficult and not worth it, though this particular example should just use a duration type instead.