Meaningful Names

What do we need to know & why it matters.

Jonathan Andrés - @jcabasc

what does this function do?

No, seriously

The way the I see, coding is like “writing a book, or an article in the newspaper”, you need to express yourself so good in a way the people would buy it.

Clean Code

That means, you have to be as clear as possible and release something understandable, no matter what language you’re using. You have to deliver clean code.

Why is important?

• People who read your code will understand.
• You will do a favor for yourself later.
• it would be easy to read, maintain or extend.

• If you're in a team with a bunch of people coding over the same code and at the same time, you will no regret of doing this.
• In the near future you can forget what does a certain thing.

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.

Use Intention-Revealing Names

// what are these?
    int ca;
    int ua;

    def get_dau
      self.order(:created_at).all.map do |item|
        [item.created_at, item.active_users.to_i]
      end

    def get_mau
      self.order(:created_at).all.map do |item|
        [item.created_at, item.unique_active_users]
      end
    end

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.
• Beware of using names which vary in small ways.
• No information at all is better than misleading information.

There is no need to call a variable customerArray if it's an active relation object.

A good name contains as many words as are needed to express a concept. But nothing more. Any unnecessary words make the name longer and harder to understand. Short names are good only when they describe the whole concept in the current context (it is better to say “customersInOrder” than “list” in a context of making an order).

Avoid Disinformation

// Long variables
      ABCModuleForEfficientHandlingOfDates
      ABCModuleForEfficientStoringOfDates

      customerList // hash
      quantity //percentage

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

it's unlikely that this happens, but in this situation it's indistinguishable zero (0) from uppercase (O) and one (1) from lower-case (l).

Make meaningful Distinctions

• Avoid misspelling names to satisfy your code.
• Number series are noninformative and noise words are meningless distinctions.
• Distinguish names in such a way that the reader knows what the differences offer.

For instance if you call a variable member2 because you already have another one call it member1.

For instance if you have a class named Product, and create two more classes ProductInfo and ProductData. You have made the names different without making them mean anything different.

Make meaningful Distinctions

//
      get_active_ccount()
      get_active_account_info()

      def copy_content(a1, a2) {
        for (int i = 0; i < a1.length; i++) {
          a2[i] = a1[i]
        }
      }

      Class CustomerInfo
      end
      Class CustomerData
      end

How we supposed to know which of these functions to call?

In the secod example, this function reads much better when source and destination are used for the argument names.

Use Pronounceable Names

People are good at words, so take advantage of that. Make your names pronounceable.

Need no explanation.

Use Searchable Names

Names should be easy to locate across a body of text.

def message
    MESSAGE if total > 0 &&  percent_with_prices <= 10
  end

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

Single-letter names can ONLY be used as local variables inside short methods.

Avoid Encodings

Encoding type or scope information into names simply adds to the burden of deciphering. They are a mental burden, seldom pronounceable and easy to mistype.

Need no explanation.

Avoid Mental Mapping

• Readers should not need to mentally translate your names into other names they already know/are familiar with.
• Legendaries i, j, k variable names are really only okay for use as loop counters if their scope is very small and no other names can conflict with them.

This problem generally arises from a choice to use NEITHER problem domain terms nor solution-domain terms.

There is no need to call a variable for its synonyms or something you think is similar within a context.

For instance if you're working in a healthcare software, and there are patients and doctors, but you decide to call them users within a scope.

Class Names

• Classes and objects should have noun or noun-phrase names, like Customer,WikiPage, Account and AddressParser.
• But avoid names like Manager, Processor, Data or Info in the name of a class.
• A class name should not be a verb.

Self-explnatory.

Method Names

Methods should have verb or verb-phrase names, like deletePage or save.

This apply for public methods. There are exceptions when you could call private methods by a word that represent the name of the object that return (Personal opinion).

Don’t Be Cute

Don’t be too clever or humourous with your names.

Name things as what they are.

Self-explnatory. In spanish "No inventes". Don't you remember the vander_fix method.

Pick One Word per Concept

• Pick and use one word for abstract concept and stick with it.
• A consistent lexicon is a great boon (helpful) to the programmers who use your code.
• ie: Do you think these methods fetch, get and retrieve could be equivalent in different classes?

For instance if you're retrieving attributes from an API in a User class, you should not call it any different in another one when you're doing the same thing.

Don’t Pun

Avoid using the same word for two purposes. Using the same term for two different ideas is essentially a pun.

For example using the term add in several classes, for “consistency”, when you are in fact not using it in the same sense. Adding an element to an array or concatenating two values.

Use Solution Domain Names

The people who read you code are programmers, so go ahead and use computer science terms, algorithm names, pattern names, math terms, and so forth, such as AccountObserver, where Observer means the Observer pattern.

If the reader is familiar with the concept, might clarify to him what is its purpose.

Use Problem Domain Names

To make code more understandable to anyone involved in solving a problem, it is better to use meaningful names in a domain context.

That means, use business language.

All code that programmers write is connected to some domain logic.

In the future somebody else (not only a programmer, maybe a tester) will use your code and will be able to easily understand it in a domain context (with business logic knowledge).

Add meaningful Context

The context is very important to understand a name, because it has additional information.

You can add context to names by using prefixes or enclosing them in well-named classes, functions, or namespaces.

Imagine that you have variables named city, state, and zipcode. Taken together it’s pretty clear that they form an address. But what if you just saw the state variable being used alone in a method? Would you automatically infer that it was part of an address?

You can add context by using prefixes: addrCity, addrState, addrZipcode or by creating a class named Address.

Don’t Add Gratuitous Context

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

A good name contains as many words as are needed to express a concept. But nothing more. Any unnecessary words make the name longer and harder to understand.

El Fin