Clean Code: Meaningful Names

This is the summary of Clean Code book specifically Meaningful Names by Robert C. Martin. Writing meaningful names one for most crucial thing in software development.

Use Intention-Revealing Names

The name of a variable, function, or class should tell you why it exists, what it does, and how it is used.

If a name requires comment then it is not revealing it’s intention. Let’s say for example,

int d; // elapsed time in days

The name d reveals nothing. Better to put,

int elapsedTimeInDays;

Benefits of reveal intented names,

• Easier to understand.
• Change Code.

Avoid Disinformation

One must avoid leaving false clues that obscure the meaning of the code.

For example, hp, aix and sco would be poor variable names because they are the name of UNIX platform.

Do not refer to a grouping of accounts as an accountList. If it is holding the accounts then it is not a list. In that case accounts as variable name would be a better choice.

Using inconsistent spelling is Disinformation. An example of it, lowercase l and uppercase O.

Make Meaningful Distinctions

If you as a programmer intention is to satisfy compiler or interpreter then you are creating some problem for yourself.

Number series naming (a1, a2, aN) this is non-informative, because the provider has no clue about author info.

function copyChars(a1, a2) {
  for(let i = 0; i < a1.length; i++) {
    a2[i] = a1[i];
  }
}

a1 and a2 both have no meaning. Better to put source and destination.

Avoid using Noise Words like,

• Data
• Value
• Info
• Variable
• String
• Object

They do not provide any additional information about the variable. They are redundant.

For example, if you have a function called getUserData this should be getUser.

Use Pronounceable Names

If you can’t pronounce it then you can’t discuss it. Compare,

class DtaRcrd102 {
  private Date genymdhms;
}

To,

class Customer {
  private Date generationTimestamp;
}

Use Searchable Names

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 name. Compare,

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

to,

let realDaysPerIdealDay = 4;
const WORK_DAYS_PER_WEEK = 5;
const NUMBER_OF_TASKS = 34;
let sum = 0;

for(let j = 0; j < NUMBER_OF_TASKS; j++) {
  let realTaskDays = taskEstimate[j] * realDaysPerIdealDay;
  let realTaskWeeks = (realTaskDays / WORK_DAYS_PER_WEEK);
  sum += realTaskWeeks;
}

Avoid Mental Mapping

If variable names are not obvious, others may misinterpret what you were meaning. Compare,

products.forEach(p => {}); // What does that p mean?

to,

products.forEach(product => {});

Now anyone can understand what is product actually.

Class Names

Classes and objects should have noun or noun phase names like Customer, Account etc.

Method/Function Names

Methods or Functions should have verb or verb phrase names like postPayment or makePayment, getEmployee etc.

Don’t Pun

Avoid using the same word for two purposes. Using the same term for two different ideas is essentially a pun. This simply means be consistent in every module of codebase.