This Overly Long Variable Name Could Have Been a Comment | Jonathan's Blog

[email protected]

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.

[email protected]

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.

[email protected]

I find vague variable names exhausting. It adds not inconsiderable mental overhead when reading code, at least for me.

[email protected]

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.

[email protected]

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 = 5 could maybe have a type that extends an int called seconds. So then you are declaring seconds Interval = 5.
It describes the unit, so the variable name just describes the purpose.
You could even add methods for fromMinutes etc. 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.

int sleepIntervalSeconds = 0;
// etc...

You could create an intervals class/object/whatever.
So then you have.

public class Intervals {
    public seconds Sleep
    public seconds Refresh
    public seconds Timeout
}

The class/object defines the context, the type defines the unit, and you get nice variable names describing the purpose.

[email protected]

You can write comments, but you can't make your colleagues read them. They don't necessarily have to visit the originating file to read the docs.

Short variable names tend to lead different people to make different kinds of assumptions about the purpose and use of the variable. Those differences in understanding is where a lot of subtle bugs come from, or causes people to hit a dead end.

Just be clear and explicit. Its not gaming; you dont have to care about losing a couple extra frames to type out a few extra characters. Most IDEs have sufficient autocompletes so it's literally not even a problem in many cases.

[email protected]

This relatively new. Only "recently" (last couple decades) was it easy to get type info for a variable where it was used.

The other problem is that if your type is merely an alias, in many languages you can still do

interval_minute = interval_second

without the compiler catching it.

[email protected]

Tbf, old comments can also give important context through earlier refactors and help avoid treading the same ground again.

That being said, this is with the assumption that the next dev making a change will add their own comments describing it.

[email protected]

My rule of thumb is, use short names if the context makes it clear. But do not make names too long and complicated (especially with Python :D). For me having unique names is also important, so I don't get confused. So not only too similar names are bad, especially if they all start like "path_aaa", "path_bbb" and such, then the eye can't distinguish them quickly and clearly. And searching (and maybe replace) without an IDE is easier with unique and descriptive names.

Sometimes its better to come up with a new name, instead adding a modification and make the name longer. This could be in a for loop, where inner loops edit variables and create a variation of it. Instead adding something like "_modified", try to find what the modification is and change from "date" to "now" instead "date_current".

[email protected]

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.

[email protected]

Nothing wrong with a, i, s and x.

[email protected]

Yeh, absolutely.
Horses for courses.

[email protected]

You say that like it can't also happen to symbol names.

[email protected]

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.

[email protected]

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.

In a company I work in, we have "no comments policy" for at least ~10 years now and we are not planning to change that. It's not just theory, we work like this in practice and purpose of each part of code is perfectly understandable just from variable names, file names, namespaces, function names.

[email protected]

// Increment i
i++;

Very info. Much useful.

[email protected]

Something’s you leave out but let’s say instead you are using some enumerator like in Python over a list of some objects. Sure you can use “i” but what if it’s a list of apples then why not make the iterator “apple”

For Apple in apples

Simple example but the concept can go a long way

[email protected]

Ah yes, one of the major questions of software development: to comment, or not to comment? This is almost as big of a question as tabs vs spaces at this point.

Personally? I don't really care. Make the code readable to whoever needs to be able to read it. If you're working on a team, set the standard with your team. No answer is the universally correct one, nor is any answer going to be eternally the correct one.

Regardless of whether code comments should or shouldn't exist, I'm of the opinion that doc comments should exist for functions at the very minimum. Describe preconditions, postconditions, the expected parameters (and types if needed), etc. I hate seeing undocumented **kwargs in a function, and I'll almost always block a PR on my team if I see one where the valid arguments there are not blatantly obvious from context.

[email protected]

This depends. Many languages support 1 liner aliases, whether that's using/typedef in C++, type in 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.

[email protected]

Congratulations, you figured out to do comments the wrong way.

You also figured out how to use a bad, unclear variable name, so should we also stop naming variables with sensible words since it can be done wrong?

External documentation can also be done badly, so let's stop doing that too.

Or what's your point?

agnos.is Forums

This Overly Long Variable Name Could Have Been a Comment | Jonathan's Blog