Being a connoisseur of writing bad code, I can probably give some advice and pitfalls to avoid. Secondly, but much less important (joking of course) has been my over 4 years of experience writing code for money.
These points probably will probably be very small and extremely easy to keep in mind while writing code. This will be a pretty long series of Conventions.
Today we take variable naming into account, an extremely basic topic but one having massive impact on overall code quality.
VARIABLE NAMING
- Probably the most well known rule but something I have personally seen juniors still struggle with this. I think it’s because the rules taught are very generic, use proper names, don’t be vague ….. But since the rules are good but extremely generic, it breeds doubt as to the correct way to name variables.
- Firstly, always (I MEAN ALWAYS) follow the existing project naming convention. Doesn’t matter if it’s a C# Project and using Camel Case, if the project follows it, you have to. There is absolutely 0 reason to break existing convention. If you do, and I am the reviewer, you have to refactor your entire change, no leniency.
- Secondly, very similar to point 1 but variable naming conventions change according to the scope of the variable and also access modifiers, so a local variable should follow different naming conventions than a class property.
- Thirdly, and this is the most important in my eyes. Variables should accurately define what it stores.
- The trick I use is very simple, look at the class name, it is your general scope, then look at the function name, it is the work that this function is performing. This gives you basic information about a lot of stuff before even reading the variable name. For example, let’s say a class of Logger -> Function: LogToFile(), I already have basic information about what the function does and have a general expectation of what to expect, so a variable like file, although a bad variable name, gives me context clues, it probably opens a file, and why? to log. This is all to say context matters to naming a variable.
- Then the most important thing, your variable names should be concise but not that concise that you miss important information. For example, in the function LogToFile() described above, the variable name file gives me enough context clues to understand what it does, but wouldn’t it be easier to read the code if the name was fileLogger ? Use as many words as you need to clearly explain what the variable does.
- As an additional example, let’s take a simple case. I have a class A, and a method B (intentionally obscured names to remove context). Task is to check if a specific operation is completed and return a boolean. The result of the operation is stored in a database. How will you do this?
- The way is of course, call the database, handle the edge cases and return the result.
- But would you store the query in a variable or hardcode it in the call to the database? The answer is depends, but most often, storing it in a variable (or better yet retrieve it from separate configuration, so the function stays flexible) is better.
- Then comes the question, what would you name the variable? Since you have extremely low context here, variable name like query, isn’t that bad. But think about it, could you make it easier for others to read? Can you add more context to the variable name? And of course there can be a million different variables with the name query, even in the same class, which isn’t terrible per se but remember what I said, “clearly identify what it stores”. Add some more context to the variable name.
- Last point, and it is me tracking back a little bit. The name of the variable should depend on the context, so in this case, if the method is completely Generic, that means the method isn’t used for a specific purpose and just Gets the query, queries the database and returns the result, probably query is the best name as it accurately defines what the variable stores. But if it’s less generic and ONLY used to check if a specific operation is completed, something like checkOperationCompletionQuery makes a whole lot more sense.
- I hope this was clear, a variable name not only depends upon the existing context but also on what it stores.
- As an additional example, let’s take a simple case. I have a class A, and a method B (intentionally obscured names to remove context). Task is to check if a specific operation is completed and return a boolean. The result of the operation is stored in a database. How will you do this?
- Fourth, something that isn’t really obvious from the outset but still follows basic principles, what to name if you are casting a variable to something else. For example, you just care about the integer part of a decimal value, what do you name then? Since you are reading this, i of course assume you won’t just name it i, j, k … But what do you name? I have seen plenty juniors break their rules in this case. And the answer is obvious, I follow this convention {existing variable name}As{new type}.
- For example, casting a value storing money as decimal, I want to cast it to int for reasons. Descriptive variable name will be moneyAsInt. It leaves 0 scope for misunderstanding what it does and as long as the existing variable name was clear, your new modified code, will be clear too.
- Lastly, what about variables you won’t ever use? The obvious question is, why even have variables you won’t use? Sometimes, a function returns a Tuple. In that case, even if you are interested in the first or second value doesn’t really matter, you will get both regardless. So in that case, when a variable is not needed at all, use _ (underscore) to denote it. Unfortunately, I primarily code in C#, so this is the convention I follow, but I cannot guarantee this is the convention, your language follows, so please google it.
End notes
I plan to add a complete before and after comparison of code following vs not following basic rules to demonstrate the usefulness of writing good code. But that will probably be at the end of this series.
The Debugging Room 