Clean Code Chapter 1&2: Clean Code & Meaningful names

I have started reading the book Clean Code by Robert C. Martin, which is considered to be a industry standard for writing maintainable and elegant code.

Because this book is such a heavy read, and each chapter is full of content and a knowledge bank in itself, for personal reference I’ve decided to summarise each chapter in a set of blog posts.

Chapter 1 : Clean Code

This was more like chapter 0. Author describes what is clean code and cost of maintaining it. How clean code is directly related to team productivity and what makes clean code clean.

It contains views on clean code by many of industries best known people like Bjarne Stroustrup, Michael Feathers etc.

One of my favourite definitions form the book covers it best :

I like my code to be elegant and efficient. The logic should be straightforward to make it hard for bugs to hide, the dependencies minimal to ease maintenance, error handling complete according to an articulated strategy, and performance close to optimal so as not to tempt people to make the code messy with unprincipled optimizations. Clean code does one thing well – Bjarne Stroustrup

Chapter 2 : Meaningful Names

Names are everywhere in software. We name our variables, our functions, our arguments, classes, and packages. Because we do it so much, we should do it well.

1. Use intention revealing names : 

The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used.

int d; // time elapsed

Here d reveals nothing. A better name would be

int timeElapsedSinceCreation;

2. Avoid Disinformation :
Programmers must avoid leaving false clues that obscure the meaning of code. We should avoid words whose entrenched meanings vary from our intended meaning.
ex

int accountsList;

Should only be named so if it is a actually a list data structure that’s used to store the accounts. Not an array or set.

3. Make meaningful distinctions
Entities named different, should be different, mean different.

If we have classes called

ProductInfo

or

ProductData

, you have made the names different without making them mean anything different. Info and Data are indistinct noise that doesn’t differentiates what they actually mean.

4. Use pronounceable names

Makes communicating about the code easy.
ex.

long genydhms;

is not a good name.

long generationTimestamp;

is a better choice

5. Use searchable names
Avoid single letter variables and constants as they are difficult to search.

6. Avoid Encodings

Hungarian notations, member prefixes, interface and implementations should be avoided.

It just adds another burden to remember the encoding format being used.

7. Avoid mental mappings
Readers shouldn’t have to mentally translate your names into other names they already know.
ex.

int r;

Where

r

is lower cased url with host name removed adds to much requires too much mental juggling and mapping when working with the code.

A better name would be,

int urlWithoutHostName;

8. Class Names
Classes and objects should have noun or noun phrase names like Customer, WikiPage, Account, and AddressParser.
Avoid words like Manager, Processor, Data, or Info in the of a class. A class name should not be a verb.

9. Method Names
Methods should have verb or verb phrase names like postPayment, deletePage, or save.

10. Don’t be cute

If names are too clever, they will be memorable only to people who share the
author’s sense of humor, and only as long as these people remember the joke.

Don’t tell little culture-dependent jokes like eatMyShorts() to mean abort().

11. Pick one work per concept
Pick one word for one abstract concept and stick with it.

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?

11. Use solution domain names
It’s OK and preferable to use names from computer science and programming domains.
ex.
In transctionObserver

the word observer means a great deal to person who knows the observer pattern.

12. Use problem domain name
The code that has more to do with problem domain concepts should have names drawn from the problem domain.
ex..

int mriRecord

In a healthcare app will give a great deal of context than just

int record

.

13. Add meaningful context
Enclose names in well named functions, classes, namespaces, etc.
ex.

String state;

In a class called FiniteStateMachine will mean different that in a class called Address.

14. Don’t Add Gratuitous Context
In an imaginary application called “Gas Station Deluxe,” it is a bad idea to prefix every class with GSD.
Frankly, you are working against your tools. You type G and press the completion
key and are rewarded with a mile-long list of every class in the system. Is that
wise? Why make it hard for the IDE to help you?

 

This was part one of a 16 part series on the book Clean Code by Robert C. Martin, where each post covers a gist of a single chapter.

Thanks!

Advertisements

The Alchemist : Reading Experience

918fZ1wVZgL.jpg

Reading The Alchemist was like getting up at dawn and seeing the sun rise, while the whole world slept.

The Alchemist doesn’t teach you anything, but you can learn a million things from it.

“Lead will play its role until the world has no further need for the lead, and then the lead will have to turn itself into gold.”

My 6th book of the year was The Alchemist by Paulo Coelho. This was a rather famous book that I finally decided to read and was not at all disappointed.

The book narrates the journey of a boy and his quest for his treasure. On the way he meets the alchemist, who helps him find the treasures he didn’t even know existed.

The boy who was a shepherd, used to travel across lands with his sheep.

He remembered that because he had the jacket, he could withstand the cold night of the desert. He knew that we have to be prepared to withstand the change, and suddenly he was grateful for the weight and warmth of the jacket, even in the scorching day time heat.

The above quote perfectly captures the importance of embracing change and suffering now for the sake of later good.

The boy had a dream of finding treasure near pyramids of the Egypt. And he later finds that this was what his personal legend was.

After all, it is the possibility of dream come true that makes life interesting.

On his way, he meets an old king. The old king who teaches the boy what one’s personal legend is.

Personal legend is what you have always wanted to accomplish. Everyone, when they are young knows what their personal legend is. At that point in their life, everything is clear and everything is possible.

The soul of the world is nourished by people’s happiness. And also by unhappiness, envy and jealousy. To realise one’s personal legend is a person’s only real obligation.

“And here I am between my flock and my treasure” – the boy thought.

And while following our personal legend, we have to choose between something we are accustomed to and something we wanted to have.

The secret to happiness is to see all the marvels of the world and never to forget the journey of your own personal legend.

But that journey is full of decisions and choices that one has to make.

Making a decision was only a beginning of things.

When someone makes a decision, he is really diving into a strong current that will carry him to places he had never dreamed of when he first made the decision.

The Alchemist’s greatest discovery was not the elixir of life or the philosopher’s stone. But, they discovered that the purification of metal had led to a purification of themselves.

A purification that made them understand the ultimate truth of life. One’s personal legend.

Journey of one’s personal legend is full of omens. Omens that represent the resonance of energy with the soul of world. And the universe communicates the omens by using the universal language.

But how does one immerse himself in his personal legend?

“Listen to your heart, it came from the soul of the world and one day it’ll return to it”.

Power of silence is what allows us to hear the world speak the universal language. The book describes

The boy was sitting in desert in silence with only sound of the laventer (east wind) hitting his face. He was learning to understand the desert.

An average person speaks 10,000 words per day. May be cut that into half. or some times don’t speak at all.

It’s all about improving himself. That’s is the reason why one’s personal legend was carved by the soul of the world. It’s the journey that one follows in his personal legend. that is the real treasure. Everything else is secondary.

This is why the alchemy exists. So that everyone will search for their treasures, find it and then want to be better than their former life.

“Lead will play its role until the world has no further need for the lead, and then the lead will have to turn itself into gold.”

And finally, towards end of the book, the boy finds his treasure right where he started.. The place where first he had the dream. When he asked the soul of the world why it didn’t tell him that before, it said,

Because it was fun! This is what your personal legend was. You had to follow it.

Conclusion : 

The most prominent lesson I learned from The Alchemist  was that one has to find and follow his personal legend. Even if the goal is right in front of them. Because in the end, it is the one’s journey on his personal legend that reveals the true treasures of life to him.

A must read for everyone!