DEV Community 👩‍💻👨‍💻

Leslie Tang
Leslie Tang

Posted on

Notes on "Clean Code" Chapter 2: "Meaningful Names"

This chapter provides a list of good naming practices with examples. Reading through the chapter gives a sense of what's good and what's bad but attempting to implement all of them at once is somewhat daunting.

Good Practices to Incorporate

  • Using Intention-Revealing Names

The names used should be self-explanatory

  • Using nouns or nouns phrase for Class Names

Examples of Good Class Names: Customer, WikiPage, Account, Address are good class names.

Examples of Bad Class Names: Manager, Processor, Emitter are bad class names since they imply some sort of action.

  • Incorporating verbs or verb phrase for Method Names

Examples of Good Function Names: postPayment(), deletePage(), save().

Accessors, mutators and predicates should be prefixed with get, set and is and named for their value.

For example, getTimeStamp(), setDateOfBirth(), isUserAvailable.

  • Using Pronounceable Names

Don't create your own acronym or words to describe something that can be communicated with normal words

  • Avoid Disinformation

I feel some of my namings might lead to wrong conclusions. One example given is "accountList" which might imply that the underlying data structure is a List. Another example is using abbreviations that might mean something else. Lastly, a mistake that I seem to keep making is the inconsistent naming of a similar concept.

  • Pick One Word per Concept

This ties in well with disinformation. For example, picking many words for the same concept might lead to disinformation, e.g. get vs fetch vs retrieve.

  • Use Searchable Names

Especially if the name is used in multiple places. A quote from the book:

"The length of a name should correspond to the size of its scope"

  • Adding Meaningful Context

For example, a function that uses state as a variable might not let you infer much, but a function that uses state, firstName, lastName, city, address, country makes it clear that it forms an address.

  • Use Solution Domain Names

Since readers of your code are fellow programmers, go ahead and use Computer Science terms be it algorithm names, pattern names, math terms, and the likes.

Bad Practices to Avoid

  • Avoid Mental Mapping

This deals with the clarity of names. For example, we do not want readers to mentally translate the provided names into other names they already know. Often this is the result of using neither Problem Domain nor Solution Domain terms.

  • Don't Add Gratuitous Context

For example, prefixing every class with the name of the application or prefixing every variable with the class name.

  • Incorporating entertainment value at the cost of clarity

For example, using whack() to mean kill(). The rule of thumb as quoted from the book:

"Say what you mean. Mean what you say."

Three Takeaways

After going through the various examples from this chapter, my personal takeaways are:

  1. Keep Naming Clear Concise
    If we can keep in mind to keep the name concise and clear, we would probably be a few steps ahead. Using nouns and verbs are some ways to achieve this.

  2. Keep Things Consistent
    I would imagine proper documentation would help in this, especially for projects that involve many contributors and span across a long period of time. Having standards laid out for everyone to follow would probably clear up miscommunication and misunderstandings.

  3. Keep the Reader in Mind
    Just as authors write with the readers in mind, we should write code with the next programmer in mind. The simple rule of thumb to accomplish this is to be explicit, be clear, and don't assume that the next person knows everything you do about the code.

I would imagine being aware of the mistakes that I'm making is the first step in rectifying them. What comes next is to maintain that awareness and slowly develop the habit.

Top comments (0)

🌚 Friends don't let friends browse without dark mode.

Sorry, it's true.