Hi guys,
Recently I started reading Clean Code by Robert C. Martin. So far I think this is a great book and every programmer should read it at least once or at the very least the starting few chapters as in those chapters the author tries to highlight the very basic and fundamental coding practices which should not be ignored ever.
In this post, I will try to summarize the second chapter of the book in my own words and will try to keep things as simple as possible. So let's start :)
The problem
"Naming" is a very important step of any process. We put a lot of thought into naming our children because we understand its importance. But when we do the same for our code, we don't have enough time for it. We either think that we already know the best naming practices or we just don't think that it's worth our time. Bad variable names might seem okay in the start but when the code base is getting bigger with many more developers working on it, it just gets so much difficult to manage and coordinate our efforts. Our code is our creation, therefore, we ought to name it properly at the very least.
What to do?
Intention of the variable should be clear from its name.
- If you have to write a comment to make the purpose of the variable clear, rethink the name.
- In the old times, we had smaller (very smaller) RAMs and thus had to think very carefully while giving variables big names. But that's not an issue now, is it?. Then why give variables vague names like
a
,n1
etc.
consider this piece of code
getData(plist):
ep = [] // expired person accounts
for p in plist:
if p.expiry_date >= datetime.now()
ep.push(p)
return ep
and compare with
get_expired_persons_list(persons_list):
expired_persons_list = []
for person in persons_list:
if person.expiry_date >= datetime.now()
expired_persons_list.push(person)
return expired_persons_list
Do not use variable names which could misguide other developers.
- An example would be naming a collection of
Person
objectspersons_list
when it is not actually aList
. This name could misguide other developers towards thinking that it is aList
type object. Therefore naming itpersons_collection
would be a better choice.
Variable names should be meaningfully distinct
- We often tend to name variables in a way that we could only get rid of compiler errors due to same variable names. An example would be to name variables
PersonData
andPersonData2
. In this example, the purpose of the variables is not clear. - Similarly if you have written a
Person
class with methods likeget_person()
,get_person_info()
, it would not be easy for other developers to call the correct method for the desired purpose. A developer can easily get confused about the functionality of any of these methods.
Variable names should be pronounceable.
- Our brain can remember the variable names easily if they are pronounceable and we can avoid the unnecessary hassle of searching for the variable name in previous code to reuse it. An example would be using names like this:
class Person(object):
...
get_age_year_month_days()
get_last_modified_year_month_days()
...
instead of
class Model01(object):
...
get_ageiymd() // get age in year, month, days
get_lmdiymd() // get last modified in year, month, days
...
Searchable variables and constants should be used.
- Suppose you have a working project. There is a requirement for every user to be at least 18 years old. You have implemented this in the following way:
def create_person(data):
if data['age']['year'] < 18:
return None
- similarly, you have used this number
18
in other places where this was required in any way.
Now the requirement is changed and the user must be at least 15 years old to create an account. What would you do to now? Search for every occurrence of number 18
and decide if this is the number used for our purpose and then change it everywhere.
Or you could have simply used a constant MIN_AGE_REQ=18
or MINIMUM_AGE_REQUIREMENT=18
(which is more meaningful and searchable). Then you would have to simply change the value of this constant to satisfy the new requirement.
Class names should always be nouns.
- Class names and objects should always be nouns like
Person
,Car
,Record
and so on. Avoid generic and language-specific technical names likeInfo
,Manager
andController
.
Method names should have a verb
- Method names should have verb or verb phrase names (preferably in the start) like
get
,set
anddelete
.
Decide a standard for names serving similar purposes.
- Say your project has lots of classes in it with many developers working on them. You decide to use the following convention for setters and getters:
class PersonUpdateForm(object):
...
get_age()
set_age()
...
while another developer might do things like this:
class UpdatePersonForm(object):
...
retrive_age()
update_age()
...
This causes inconsistency in the project and difficult to search for desired objects and methods.
Decide ahead of starting the development that what kind of conventions are you going to follow and have every developer follow those.
Use context with variable names wherever is necessary.
- If you have a variable named
state
inside a classMemberAddress
then it is clear that thestate
belongs to aMemberAddress
object. but outside the class, if the variablestate
is used then it may not be clear for other developers that the variablestate
belongs to what object. In that scenario using the variable name,member_address_state
would be more meaningful.
Conclusion
We should never ignore the importance of naming practices as bad variable names would become a big hurdle in future development plans. Changing the codebase at that point is unnecessary overhead and can be avoided in the very beginning by following good practices.
This is all from my side for now. I will write soon about the later chapters of the book.
Happy coding!
Top comments (3)
Danial,
I have a class with 200 lines of code. I need to add 5 more methods to it. the class is called Member. Other than it accesses the 'member' table in my database, the new methods have nothing to do with the rest of the class. Any thoughts on what to name the second class other than Member2.
Thanks,
Ken
Thank you so much for this post. I'm just starting a bachelors in Software Engineering. This has been extremely helpful.
Thanks for the article, this is really precises.