🎯Coding Best Practices

A few critical notes from Clean Code on naming things

General

"Indeed, the ratio of time spent reading vs. writing is well over 10:1. "

• Indeed, the ratio of time spent reading vs. writing is well over 10:1. We are constantly reading old code as part of the effort to write new code.

• Because this ratio is so high, we want the reading of code to be easy, even if it makes the writing harder. Of course, there’s no way to write code without reading it, so making it easy to read makes it easier to write.

• Don’t be afraid to spend time choosing a name.

• It is not at all uncommon that hunting for good name results in a favorable restructuring of the code.

• Be consistent in your names.

“You know you are working on clean code when each routine turns out to be pretty much what you expected.”

Class Names

• use noun or noun phrases

• class names should not be verbs

Method Names

• use verb or verb phrases

Function Names

• use verb or verb phrases

• use descriptive names

• Don’t be afraid to make a name long.

  • A long descriptive name is better than a short enigmatic name.

  • A long descriptive name is better than a long descriptive comment.

Pick One Word Per Concept

• pick one word per abstract concept and stick with it

• for instance, it’s confusing to have fetch, retrieve, and get as equivalent methods of different classes

• avoid using the same word for two purposes

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. It is not wise to draw every name from the problem domain because we don’t want our coworkers to have to run back and forth to the customer asking what every name means when they already know the concept by a different name.

The name AccountVisitor means a great deal to a programmer who is familiar with the VISITOR pattern. What programmer would not know what a JobQueue was? There are lots of very technical things that programmers have to do. Choosing technical names for those things is usually the most appropriate course.

Use Problem Domain Names

When there is no “programmer-eese” for what you’re doing, use the name from the problem domain. At least the programmer who maintains your code can ask a domain expert what it means.

Separating solution and problem domain concepts is part of the job of a good programmer and designer. The code that has more to do with problem domain concepts should have names drawn from the problem domain.

Add Meaningful Context

“Don’t comment bad code—rewrite it.”

• There are a few names that 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.

• Shorter names are generally better than longer ones, so long as they are clear. Add no

  more context to a name than is necessary.

React Coding Standards

• Component names should have the type of the component at the end of the name (e.g. a Card would be ThisFancyComponentCard). The very last word of every component should indicate its intended category of use. The left-hand side of the name should represent the problem-domain language.

• Remove all unused files and imports and code from the code base. Better to .gitignore a folder if you need temporary files for reference.

• Reserve ternary operators, anonymous arrow functions, etc to the domain of one-liner code.

• Avoid words like “first” or “final” etc in names since you never know what may come before or after.

• Organize code such that readers are not required to read implementation detail.

• Unless there is a good reason to do so, avoid inverting boolean values in a conditional check. Write true-case code before false-case code.

• Be sure to include time for refactoring and renaming efforts.