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

[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?

[email protected]

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.

[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.

When do you need documentation? When you are down in the code or when you are sitting on the toilet browsing Confluence? If your goal is to make people read the documentation, then the documentation needs to be immediately there where you need it, not in some external thing like Confluence.

Same goes with if your goal is to make people update the documentation. That's much more likely to happen if the documentation is in a comment in the code than when you first have to go hunting to find the correct page in that steaming pile of mess that is confluence.

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.

You still only got so much screen real estate, and having huge names means that your lines get very long at times, which makes everything really hard to read.

[email protected]

With symbol names it's trivial to notice and refactor. Comments, not so much.

[email protected]

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.

[email protected]

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.

[email protected]

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.

[email protected]

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.

[email protected]

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

agnos.is Forums

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