Meaningful Names

Names are everywhere in software. We name our variables, our functions, our arguments, classes, packages, source files, directories, ... What follows are some simple rules for creating good names.

Use intention-revealing names

The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent.

What does the list represent?

List<User> theList; // The list of users

List<User> users;

Avoid disinformation

Programmers must avoid leaving false clues that obscure the meaning of code. We should avoid words whose entrenched meanings vary from our intended meaning.

Of what type is the account list? String? Array of strings? Array of objects?

accountList

accounts

The lower-case L or uppercase O ? or they look almost entirely like the constants one and zero, respectively.

int a = l;
if ( O == l ) {    
  a = O1;
} else {    
  l = 01;
}

Avoid similar shapes

How long does it take to spot the subtle difference?

class ControllerForEfficientHandlingOfStrings class ControllerForEfficientStorageOfStrings

Make meaningful distinctions

How do these different names convey different meanings?

class Product class ProductInfo class ProductData

Use pronounceable names

How can you discuss it without sounding like an idiot?

class CstmrRcrd

class CustomerRecord

Use Searchable Names

Single-letter names and numeric constants have a particular problem in that they are not easy to locate across a body of text.

What is the number 34 , 4 or 5?

for (int j = 0; j < 34; j++) {    
  s += (t[j] * 4) / 5;
}

private static final int REAL_DAYS_PER_IDEAL_DAY = 4;
private static final int WORK_DAYS_PER_WEEK = 5;
private static final int NUMBER_OF_TASKS = 34;

public static int sumOfRealTaskWeeks(int[] taskEstimates) {    
  int sum = 0;    
  for (int j = 0; j < NUMBER_OF_TASKS; j++) {        
    int realTaskDays = taskEstimates[j] * REAL_DAYS_PER_IDEAL_DAY;        
    int realTaskWeeks = (realTaskDays / WORK_DAYS_PER_WEEK);        
    sum += realTaskWeeks;    
  }    
  return sum;
}

Avoid Encodings

It hardly seems reasonable to require each new employee to learn yet another encoding “language” in addition to learning the (usually considerable) body of code that they’ll be working in.

void tạoNgườiDùng()

void createUser()

Member Prefixes

Don’t need to prefix member variables with m_ anymore. Your classes and functions should be small enough that you don’t need them.

class Part {    
  private String m_dsc; // The textual description
      
  void setName(String name) {        
    m_dsc = name;    
  }
}

class Part {    
  private String description;    
  
  void setDescription(String description) {        
    this.description = description;    
  }
}

Interfaces and Implementations

interface IShapeFactory {}

class ShapeFactory implements IShapeFactory {}

interface ShapeFactory {}

class ShapeFactorImpl implements ShapeFactory {}

or

interface ShapeFactory {}

class CShapeFactor implements ShapeFactory {}

I don’t want my users knowing that I’m handing them an interface. I just want them to know that it’s a ShapeFactory. So if I must encode either the interface or the implementation, I choose the implementation.

Avoid Mental Mapping

This is a problem with single-letter variable names. Certainly, a loop counter may be named i or j or k (though never l!) if its scope is very small and no other names can conflict with it. This is because those single-letter names for loop counters are traditional. However, in most other contexts a single-letter name is a poor choice.

List<Student> l = getStudents();
for (Student i : l) {    
  i.doSomething();
}

List<Student> students = getStudents();
for (Student student : students) {    
  student.doSomething();
}

Class Names

Classes and objects should have noun or noun phrase names.

class Customer class WikiPage class Account

Avoid words (in the name of a class)

Manager Processor Data Info

Core

Helper

Common

Utilities

JwtHelper

MediaType {

public static final String APPLICATION_PDF_VALUE = "application/pdf";

public static final String IMAGE_JPEG_VALUE = "image/jpeg";

public static final String APPLICATION_JSON_VALUE = "application/json";

}

HttpMethod {GET, POST, PUT}

HttpStatus {CREATED, ACCEPTED, NO_CONTENT}

StringUtils

RandomUtils

TagUtils

The class name means the class does more than one thing. It doesn't say anything specific

Method Names

Methods should have verb or verb phrase names like postPayment, deletePage, or save. Accessors, mutators, and predicates should be named for their value and prefixed with get, set, and is according to the JavaBean standard.

void postPayment() void deletePage() void save()

Prefer methods to constructors overloaded

When constructors are overloaded, use static factory methods or builders with names that describe the arguments.

class User {    
  private String firstname;    
  private String lastName;    
  private int age;    
  
  public User() {
  }    
  
  public User(String firstname) {        
    this.firstname = firstname;    
  }    
  
  public User(String firstname, String lastName) {        
    this.firstname = firstname;        
    this.lastName = lastName;    
  }    
  
  public User(String firstname, String lastName, int age) {        
    this.firstname = firstname;        
    this.lastName = lastName;        
    this.age = age;    
  }
}

User user1 = new User("GP");
User user2 = new User("GP", "Coder");
User user3 = new User("GP", "Coder", 32);

class User {    
  private String firstname;    
  private String lastName;    
  private int age;    
  
  public static class UserBuilder {        
    private User user;                
    
    public UserBuilder withFirstName(String firstName) {            
      user.firstname = firstName;            
      return this;        
    }        
    
    public UserBuilder withLastName(String lastName) {            
      user.lastName = lastName;            
      return this;        
    }       
    
    public UserBuilder withAge(int age) {            
      user.age = age;            
      return this;        
    }                
    
    public User build() {            
      return user;        
    }    
  }
}

User user1 = new User.UserBuilder()
                .withFirstName("GP")
                .withLastName("Coder")
                .withAge(32)
                .build();

Adjust the length of a name to the size of its scope

Is it obvious outside the class body that WD is an acronym for work days per week?

public static final int WD

public static final int WORK_DAYS_PER_WEEK

If a variable or constant might be seen or used in multiple places in a body of code, it is imperative to give it a search-friendly and meaningful name.

Avoid using the same name for different purposes

What does add mean? Concate strings? Insert a record in a table? Append a value to the end of an array?

function add(value)

function concate(value) function insert(value) function append(value)

Use Solution Domain Names

Remember that the people who read your code will be programmers. So go ahead and use computer science (CS) terms, algorithm names, pattern names, math terms, and so forth.

The name AccountVisitor means a great deal to a programmer who is familiar with the Visitor Pattern.

Use problem domain names

What does the term "document" mean in the archives domain? Are photos considered documents?

document

record

Add Meaningful Context

There are a few names which are meaningful in and of themselves—most are not. Instead, you need to place names in context for your reader by enclosing them in well-named classes, functions, or namespaces. When all else fails, then prefixing the name may be necessary as a last resort.

What does a comma , mean? How to change all of them for a specific context?

public static final String COMMA = ",";
String extractCountry(String address) {    
  final int COUNTRY_INDEX = 0;
  return address.split(COMMA)[COUNTRY_INDEX];
}

void parseCsv(String csvLine) {    
  String[] parts = csvLine.split(COMMA);
}

public static final String ADDRESS_SEPARATOR = ","
String extractCountry(String address) {  
  final int COUNTRY_INDEX = 0;  
  return address.split(ADDRESS_SEPARATOR)[COUNTRY_INDEX];
}

public static final String CSV_SEPARATOR = ",";
void parseCsv(String csvLine) {    
  String[] parts = csvLine.split(CSV_SEPARATOR);
}

Don’t Add Gratuitous Context

package com.gpcoder.entity.obnk;

class ObnkConsentEntity {};

class ObnkAdrEntity {};

package com.gpcoder.entity.obnk;

class ConsentEntity {};

class AdrEntity {};

Shorter names are generally better than longer ones, so long as they are clear. Add no more context to a name than is necessary.

Add context by using prefixes

What does the state represent? Condition or country?

state

addressState

The names accountAddress and customerAddress are fine names for instances of the class Address, but could be poor names for classes.

If you need to differentiate between MAC addresses, port addresses, and Web addresses, consider PostalAddress, MAC, and URI.