Clean Code – Names

So, I’m looking more into Clean Code and watching Bob Martins videos for that. They are very understandable and entertaining, so if you have the time give them a look, but if you only want some information about what he’s talking about, maybe here is the right post for you.

Names are one of the most important things for the communication in our code. Good naming is important for others to understand what you are doing or, sometimes, trying to do.

Reveal your intent: If you need a comment to explain it, the name doesn’t reveal the intent. It’s a bad name.

Describe the problem: If you have to read the code to understand the name, the name doesn’t describe the problem. It’s a bad name.

Avoid disinformation: For example, example, giving an abstract class a concrete name is disinformation. It’s a bad name.

Pronounceable names: If you can’t talk about your code with your colleagues because of the pronunciation, it’s a bad name.

Avoid encodings: Your IDE is always happy to tell you the type of a variable, you don’t have to put that information in the name. ICustomer seems informative at first sight but do I really need to know at first sight if I’m using a concrete class or not? (Honestly, I personally kinda like this short information in the name, but I saw projects that are very understandable without it.) So if you are using an encoding in your name, it’s a bad name.

Parts of speech: Classes and variables should be nouns and methods should be verbs or verb phrases. A lot of times a variable holds a specific object. For example, a customer variable probably holds an object of the type Customer, so it makes a lot sense to choose the name of the variable depending on the object it holds, for this example: customer. Boolean variables should get a predicate as their name, for example: isGoldMember. It’s good for the understanding in an if statement:

if (isGoldMember){
   subsriptionFee = SubsriptionFee.GOLD;
}

The name of a method that returns a boolean should also be a predicate, because it will also get used in an if statement. So, for example:

if (isGoldMember()){
   order.includeGift();
}

Don’t use nouns for accessor. For example for names, use a getter like getName();
Enums are mostly a state description, so they should (mostly) be named with adjectives.

The scope length rule: The scope length rule: The name of the variable should be longer if the scope is longer. For example, if you are using an object of the type BufferedWriter far away from its declaration, you should properly name it bufferedWriter. That way you know exactly which type this variable has without looking somewhere else in the code. If you are using the BufferedWriter in a short scope, you can give the variable a short name, for example:

private void write (BufferedWriter bw){
   bw.write("Hello world");
}

For classes and methods this role is the opposite: the name should be longer for a short scope and short for a long scope. A public method gains more intelligibility with a shorter name, because it (probably) gets called from a lot of different places.