Clean code — Meaningful names (p3)
Right now I’m reading for the second time, the great book Clean Code by Robert C. Martin aka Uncle Bob and I think it’s a good idea to write down the most important ideas that it tries to convey to us. Today, I will focus on the second chapter.
Class Names
Classes and objects should have noun or noun phrase names like Customer, WikiPage, Account, or AddressParser. Avoid words like Manager, Processor, Data, or Info in the name of a class. A class name should not be a verb.
Method Names
Methods should have verb or verb phrase names like postPayment, deletePage, or save. Accessors, mutators, and predicates should be named for their value and prefixed with get, set, and is according to the JavaBean standard.
When constructors are overloaded, use static factory methods with names that describe the arguments. For example:
Complex fulcrumPoint = Complex.FromRealNumber(23.0);is generally better than
Complex fulcrumPoint = new Complex(23.0);Consider enforcing their use by making the corresponding constructors private.
Pick One Word per Concept
Pick one word for one abstract concept and stick with it. For instance, it's confusing to have fetch, retrieve, and get as equivalent methods of different classes. ¿How do you remember which method name goes with which class?
The function names have to stand alone, and they have to be consistent in order for you to pick the correct method without any additional exploration.
Likewise, it's confusing to have a controller and a manager, and a driver in the same code base. ¿What is the essential difference between a DeviceManager and a ProtocolController? ¿Why are both not controllers or both not managers?¿ are they both Drivers really? The name leads you to expect two objects that have very different types as well as having different classes.
Don't pun
Avoid using the same word for two purposes. Using the same term for two different ideas.
If you follow the “one word per concept” rule, you could end up with many classes that have, for example, an add method. As long as the parameter lists and return values of the various add methods are semantically equivalent, all is well.
However one might decide to use the word add for “consistency” when he or she is not in fact adding in the same sense. Let's say we have many classes where add will create a new value by adding or concatenating two existing values. Now let's say we are writing a new class that has a method that puts its single parameter into a collection. ¿Should we call this method add? it might seem consistent because we have so many other add methods, but in this case, the semantics are different, so we should use a name like insert or append instead. To call the new method add would be a pun.
Use Solution Domain Names
Remember that the people who read your code will be programmers. So go ahead and use computer science terms, algorithm names, pattern names, math terms, and so forth.
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.
Conclusions
The hardest thing about choosing good names is that it requires good descriptive skills and shared cultural background. This is a teaching issue rather than a technical, business, or management issue. As a result, many people in this field don’t learn to do it very well. Try to don’t be part of these people.
