Meaningful Names

There are only two hard things in Computer Science: cache invalidation and naming things.

— Phil Karlton

Use Intention-Revealing Names

The name of a variable, function, or class should tell you

  • why it exists.

  • what is does.

  • how it is used.

For example, comparing this one:

int enemies = 10; // Record the number of remaining enemies.

with this one:

int num_remaining_enemies = 10;

Obviously, the second one, which is expressive without a comment, is much better.

Avoid Disinformation

  • Does it imply its type?
    pointVector ⇒ std::vector<Point> ?

  • How to quickly spot their difference?
    NTUPlacerForEfficientPlacingOfMacros
    NTUPlacerForEfficientRoutingOfMacros

  • WTF?
    if (O == l)
    if (O == 1)
    if (0 == l)
    if (0 == 1)

Make Meaningful Distinctions

  • Do not use number-series
    a1, a2, …​, aN

  • Do not add noise words
    Product
    ProductInfo
    ProductData

Use Pronounceable Names

Good for communications.

For example,
“Hey, Nady, What’s the purpose of class CustmrRcrd?” vs
“Hey, Nady, What’s the purpose of class CustomerRecord?”

Use Searchable Names

Do not use single-letter name and numerics constants.

Personally, I use single-letter names only in the following situations:

  • Loop control variables

for (int i = 0; i < 10; ++i)

  • Math symbols

from sympy import Symbol, limit, oo
n = Symbol("n")
e = limit((1 + 1 / n) ** n, n, oo) # Euler's number

Avoid Encodings

Do not encoding type or scope information into names.

For example,

  • no Hungarian notation.

  • no member prefix (or suffix), such as m_ or _m.

However, I prefer to append an underscore to a member variable. [1]

class Person {
  std::string name_;
  int age_;
};

Avoid Mental Mapping

Do not show off your smart.

For example, use pswd_8aAd to represent a password which must have at least

  • 8 lower-case alphabet

  • 1 upper-case alphabet

  • 1 digit

Can you see the logic behind this name instantly?

Be professional: Clarity is king.

Class Names

Do use a noun.

Avoid words like Manager, Processor, Data and Info.

Nevertheless, I have seen some code containing classes with Manager in their names, and it still works great. For example, ABC, a program that I recently used, has some type names ended with Man, and not only is it well-maintained, but also improved constantly. Therefore, I don’t think that using Manager in names should be prohibited completely, yet it should not be abused. I think the proper scenario to use it would be a container-like class. For example, if you need a class to manage resources like Circuit objects, and there is no logically right name for the class, picking CircuitsManager would be acceptable. It’s a last resort IMO though.

Method Names

Do start with a verb.

I prefer to name accessors and mutators in the following way:

Vertex source;
source.SetName("src");
source.Name(); // "src"
source.IsVisited(); // false

Don’t Be Cute

Do not try to be humorous.

For example, choose DeleteTable() over Boom().

Pick One Word per Concept

Do choose only one word for a concept.

For example,

  • retrieve, fetch or get

  • display, show or print

  • eliminate, remove or delete

Recently, I start learning Promise in JavaScript, having a hard time coming up a rational naming rule for functions that return Promise. The reason why it is so difficult to name these functions is that we usually want to get a result from calling them. However, instead of getting the result we want immediately, we get a Promise, an object that will give you the result only at some point. So what the function return is essentially a result that is still loading.

Here is a solution that may be somehow desirable.[2]

const imageLoading = loadImage(url);
imageLoading
  .then(onFulfillment)
  .catch(onRejection);

Don’t Pun

Do not use the same word for two different ideas.

Beware of the consistency trap. For instance,

class Sequence {
 public:
  Sequence(const std::vector<int>& numbers) : numbers_(numbers), sum_(0) {}

  void AddNumber(int n) {
    sum_ += n;
  }

  void AddElement(int n) { // AppendElement is better.
    numbers_.push_back(n);
  }

 private:
  std::vector<int> numbers_;
  int sum_;
};

Use Solution Domain Names

Do use computer science terms, algorithm names, pattern names, math terms, and so forth.

Use Problem Domain Names

Only when there is no corresponding solution domain name for the problem.

Add Meaningful Context

Some common approaches:

  • Extract into a separate class
    state ⇒ class Address { std::string state_; };

  • Add prefix
    state ⇒ address_state

However, the second method is not recommended.

Don’t Add Gratuitous Context

For example, account_address and customer_address are fine names for instances of class Address, but could be bad names for classes.

1. Usually, I follow Google C++ style guide.
2. It’s the best suggestion AFAIK.

results matching ""

    No results matching ""