I’ve started watching the videos of CleanCoders. It’s a set of videos by Uncle Bob (Robert C. Martin), in which he talks about various programming topics as well as design concepts, OOP theory and so on. It’s just a amazing source of wisdom and joy. Anyway, I decided to write one post per video that I watch, hopefully it will help me to understand better the concepts.
1. Choose your names thoughtfully
The first step here is to understand that names play an important role in you code. They are not only random letters put together, they should communicate their intent clearly. If you have to use a comment to explain what that name means, you failed.
2. Avoid Disinformation
For me, this is the worst sin a programmer can commit. Think about the following code:
Yes, I know it’s a contrived example but you get the point. Now imagine you see an instance of
Pair somewhere down the road without knowing about its implementation. That would take you some time until you realize how disgraceful the name
Pair is for an object that takes 3 values.
But let’s assume you’re not so evil (no one is). What normally happens, as the code grows, is that some methods might change and at some point what they do no longer represent what their names communicate. A name should say what it means and mean what it says. Don’t forget that if you have to read the code to understand what the name means, you failed.
3. Pronounceable Names
Raise your hand if you’ve already named a variable something like
usr_name, \o/. Why don’t we write
user_name? It can’t be because we’re lazy, right?
We’re writing code that other people will read and possibly talk to us about it so make it easy for them, pick names that they can pronounce.
4. Avoid Encodings
Have you ever seen a variable called
name_str just because it was String typed? Or a class called
IAccount because it’s an interface? With the IDE’s we have full of tips about our variables and autocomplete stuff, it doesn’t make much sense to use these name encodings, even more for folks that program in a statically typed language, the compiler will get you if you’re wrong. For those who don’t (ruby anyone?), let your tests do the job.
5. Use the Parts of Speech well
According to Grady Booch, clean code should read like an well written prose. It means, we’re telling a story with our methods, functions, classes, variables, etc. What do we need to write a story? Yes, you’re right, we need nouns, verbs, predicates and so on. For example:
|class / variable||Account / account||nouns|
The goal here is to make sure that each line of your code reads like a normal phrase.
6. Scope rules
Variables name should be short (even to the size of one letter), if their scope is tiny and should be long if their scope is long. For example:
In this case, the one-letter variable
u is not that harmful because we can directly see that it’s an user. But if you stick an
u 20 lines bellow where it was declared, the person who’s reading the code will probably have problems to remember what that variable represents.
Method and classes names follows the opposite rule. Their names should be short if they have a long scope (in this sense, if they are used widespread in your code), and should be long and descriptive if they have a short scope. For example:
Notice that the method
serve has a short name and might be used in many places through out the code, but the
close_enclosing_service_in_separate_thread is used in a short scope and thus can be long a explain its intent with more words.
Remember, we’re not (maybe you are) programming in C and we’re not in the 90s anymore. Our tools became powerful with code analysis, type checking and coffee making and so on. We also don’t need to save 5 bytes by shortening all the names.