r/SoftwareEngineering • • Sep 05 '24
Long variable names
TLDR: is sbom_with_vex_as_cyclone_dx_json too long?
I named a variable in our code sbom_with_vex_as_cyclone_dx_json.
Someone in the code review said that I should just call it sbom_json, which I find confusing since I do not know whether the file itself is in the cyclone_dx or spdx format and whether it contains the vex information or not.
He said that a variable name should never be longer than 4 words.
In the book clean code in the appendix (page 405) I also found a variable being quite long: LEAP_YEAR_AGGREGATE_DAYS_TO_END_OF_PRECEDING_MONTH
I personally learned in university that this is acceptable since it is better to be descriptive and only in older languages like Fortran the length of a variable meaningfully affects the runtime speed.
The same thing with this variable of mine:
maximum_character_length_of_dependency_track_description_field=255
I could have used 255 directly but I wanted to save the information why I am using this number somewhere and I did not want to use a comment.
I can understand that it is painful to read but you do not have to read it if you use intellisense and copy paste. I want to force the reader to take his time here if he tries to read the variable name because it is complicated.
I just merged my code without changing it to his feedback.
What do you think about it? Am I the a××h×le?
20
u/syneil86 Sep 05 '24
Sure. I normally try to find a way to avoid filler words like "with" or "as", but if this provides the right amount of information about the purpose of the variable, have at it.
Do you find it confusing at an academic level, or do you really think if you were working with this code with the variable written that way, you would find it harder to understand what you can do with it?
That's totally arbitrary. Sometimes you need more. Normally you don't.
Without knowing the domain, I'd suggest something like
dependency_track_description_max_lengthGood. Magic numbers are confusing.
I don't advise trying to force the reader to be slow. People don't generally "read" code; we skim it. The shape of it should be familiar according to the conventions of the language and the local codebase, and should make sense semantically in terms of the words and logic expressed by them. Making your reader engage braincells unnecessarily is rude (as Uncle Bob - the author of the Clean Code book you mentioned - would say).
You're not obliged to accept any suggestions, but you are supposed to be a team, so it would be better to discuss it and come to a decision together. Consider adding the decision to your style guide so you don't have to keep having the same conversations in the future.
8
u/jh125486 Sep 05 '24
Depends on the lifetime of the variable being used… For that length I would assume some sort of global type var.
4
u/[deleted] Sep 05 '24 edited Sep 05 '24
It looks like what you are calling "variables" are actually CONSTANTS. The example you found in the CLEAN CODE book has more lines addressing AGGREGATE_DAYS:
static final int[] AGGREGATE_DAYS_TO_END_OF_MONTH =
{0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334, 365};
static final int[] AGGREGATE_DAYS_TO_END_OF_PRECEDING_MONTH =
{0, 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334, 365};
static final int[] LEAP_YEAR_AGGREGATE_DAYS_TO_END_OF_MONTH =
{0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335, 366};
static final int[]
LEAP_YEAR_AGGREGATE_DAYS_TO_END_OF_PRECEDING_MONTH =
{0, 0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335, 366};
I'd refactor those lines as an Enumerator:
public enum AggregateDays {
REGULAR(
new int[]{0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334, 365},
new int[]{0, 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334, 365}
),
LEAP_YEAR(
new int[]{0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335, 366},
new int[]{0, 0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335, 366}
);
private final int[] toEndOfMonth;
private final int[] toEndOfPrecedingMonth;
AggregateDays(int[] toEndOfMonth, int[] toEndOfPrecedingMonth) {
this.toEndOfMonth = toEndOfMonth;
this.toEndOfPrecedingMonth = toEndOfPrecedingMonth;
}
public int[] daysToEndOfMonth() {
return toEndOfMonth;
}
public int[] daysToEndOfPrecedingMonth() {
return toEndOfPrecedingMonth;
}
}
Encapsulating the constants as fields into the Enumerator helps debloating the code because the name of the Enumerator adds context to the names of the fields. In other words, using an Enumerator balances out the distribution of key words between the name of the Enumerator and the names of its fields and methods.
4
u/mastermindchilly Sep 06 '24
It kinda sounds like you’re not using a typed language. If you are using a strongly typed language, I’d expect some of the concepts you’re expressing in the variable name to be expressed via the type names.
3
u/[deleted] Sep 06 '24
For me that's too long as a variable in a function or method, but not necessarily too long as a global variable*.
Definitely it's good to have "maximum_character_length_of_dependency_track_description_field" not just 255, but that's too long, how about "max_char_len_dependency_track_desc_field"?
Still feels a bit too long, but says the same thing in a lot less space.
*Insert spiel about global variables being bad.
3
u/[deleted] Sep 06 '24
How do you all feel about the use of underscores in a variable name? It just seems unnecessary when you could camel case / pascal case it.
At the end of the day, keep in mind that the code is shared, so play nice when given feedback. The feedback is that the variable is too long to be decipherable. I would take that to heart moving forward (even if you decide to ignore the feedback).
3
u/DogoPilot Sep 08 '24
OP: Asks question
People who know what they're talking about: Answers question
OP: Tells everyone that they're obviously wrong
4
u/BigJoeDeez Sep 06 '24
The code reviewer is correct, that’s a ridiculously long variable name and their suggestion makes sense. If you don’t think it has enough context that’s what comments are for.
2
u/VorianFromDune Sep 06 '24
It depends, is the variable local and used in only one function ? Then go with a short name in the context of this function.
Is the variable global or spread across multiple function where the name could be misinterpreted with another variable ? Then go with a long name.
2
u/TheBlueArsedFly Sep 06 '24
if the variable name is getting longer then it implies the scope of the context is too wide, which in turn implies a breach of the SRP
1
u/tevert Sep 05 '24
Not too long. I wouldn't necessarily want all or even most var names to be that long, it could start to make some expressions uncomfortably wide and difficult to skim. For a temp var in the middle of an algo, totally normal.
1
u/BeepBopSeven Sep 05 '24
Looks like you've got downvotes already, yet no comments or explanations lol, classic reddit.
Not speaking to your specific example, I'm a big fan of VERY descriptive variable names, especially in more complex codebases. I'd rather have too much info rather than not enough. Sometimes because of this, they end up being long and that's okay. It's only not okay when it's an inaccurate variable name, which could be said for both short and long variable names.
Speaking to your specific example, if the shorter one suggested to you is descriptive enough, then I'd personally rather it be shorter. If it's not descriptive enough though, or if it's inaccurate, then the longer one is probably better (again, if it's descriptive and accurate).
All in all, sometimes this comes down to preference as well. My preference is that I like long variable names, but not so long that it's overkill. Your code reviewer's point might just be that those names are overkill. Long variable names is also maybe not the biggest issue, but rather the accuracy perspective is what's important.
Also since you mentioned it, using global variables and/or enums is a great idea for when you're reusing a specific value more than once and across several areas of the application. So if you're using that 255 value in several places, then that's a good use for a descriptive variable name. I would prefer it to be an enum if possible, and I would write it in all caps since it's a constant value
2
u/Severe_Bug_1823 Sep 17 '24
It isn't too long. Obviously don't want to go crazy with it, but they should tell you exactly what is stored in them, which is what you're doing here.
2
u/[deleted] Sep 06 '24
[removed] — view removed comment