Tuesday, May 21, 2013

The Art of Naming


1
2
3
4
5
6
7
8
public class Handler {
    
    private String data;
    private String temp;

    public int c(int a, int a2){
        int result = a+a2;
        //...


Why is Naming so important?

Because its a matter of Quality.
Naming = Readability = Understandability = Maintainability = Quality.
Good Names make your code readable, which is an essential feature for every person that has to work on it, including yourself. Soon after written, you'll forget about the details. Getting into it and understanding again can be tough and frustrating. The right Names will redeem yourself and others from those barriers. You'll might think for yourself: "No!!! I don't have the time to make this all clean and perfect. I just have to get the thing done as fast as possible, and it's no problem because i won't have to deal with it after its finished anyways..." - That's just wishful thinking. Software never ever becomes completed. Thats part of its nature. In fact, the opposite is the truth: By choosing the right names carefully, you save a lot of time from the very first day on. You keep your mind free of needless noise that slows your progression down.

How to choose the right Names?

According to "Clean Code", Names should:
  • Be intention revealing
  • Avoid disinformation
  • Make meaningful distinctions
  • Be pronounceable
  • Be searchable
But i'll add one point
  • be unmistakable (which might already be part of avoiding disinformation)

Be skeptical about a name in the first place, and dont accept it until every bit of skepticism has been eliminated. Complete Words are usually better than Acronyms, AND .... avoid redundancy!!

1
2
3
class Book{

  public String[] bookPage; // Don't repeat book since its given in the classname!

The art is to combine good names so that your code becomes a meaningful, selfdocumenting story.

1
if(plant.needsWater()) gardener.water(plant)

Classes, Interfaces and Abstracts

Stay away from 'Manager', 'Handler' and the such. 'SomethingManager' doesn't mean anything specific and is clearly not unmistakable. Use Design Patterns in your Names. They are common knowledge and give a good information about what a Class is doing. Eg.: ShadowedBorderDecorator. Name Interfaces as what they are, and don't add Pre- / Suffixes to them (IFoo, BarInterface). Client-classes don't care if they work on Interfaces or Implementations. And it's not the Names job to indicate it's Type. You dont name a Variable intNumber either, do you? It's a violation of the DRY principle. Using Abstract in a Classname is debatable. While it's pretty common, it still violates the DRY principle. Decide for yourself.

Common Errors in Variablenaming


Repeating Type in Variablenames:

1
2
3
4
Timestamp creationTime;
Date date;
String[] bookArray;
SomeType somethingObject

Adding "is" as a Prefix to booleans:
isActive. So the getter becomes isIsActive() or what?

Consecutive numbers.
There is nothing harder to read than a calculation using a1, a2 and a3 multiple times.

Generic names:
temp, data, other, object, result, value and so on

Inconsistency:
Mixing multiple Naming Strategies, or choosing one without 100% sticking to it.
E.g.: Mixing camelCase with under_scored

3 comments:

  1. What if language syntax does not allow to use some class names? For example, "Default" or "Abstract" class name is not allowed in PHP. I have interface named "Page" and I want to have some abstract class which will be extended by all page classes and implement "Page" interface. How should I name this class?

    ReplyDelete
    Replies
    1. You don't want to name a class just "Abstract" or "Default", since it wont give any information on what its for, which is the "Page".
      So you could combine these words.
      class AbstractPage { ...
      or
      class DefaultPage { ...
      or
      class BasePage { ...
      could be examples.

      In your case, maybe you don't need the interface Page and your Abstract Class could have the name "Page".
      If there are some predicates, that you still want to define in an Interface you could make a new interface "Pageable"

      In the end the result could be:
      abstract class Page implements Pageable{
      ..

      Delete
  2. Generic names (temp, data, other, object, result, value) aren't always bad. For example:

    - I always use variable "result" for returned value from method. It leads my attention to what is being built in method. Otherwise I would probably give a name similar to method name which is violating DRY principle and IMHO is worse than using generic name.

    - In equals() method, when argument passes instanceof test, I usually cast it to Foo that = (Foo)o. Since that is similar to this, comparisons of particular field can be pretty formatted in columns.

    ReplyDelete