Writing Clean Code — Being a Professional [Cheat Sheet + Video]

5/5 - (1 vote)
Writing Clean Code

Download the cheat sheet here (direct PDF download):

Have you ever asked yourself, “What does it mean to be a professional?”

This article is about being a professional software developer. It is based on the book, Clean Code by Robert C. Martin. All quotations are from this book. 

While reading this article, you will learn what it means to be a professional, what clean code is, and why you should write clean code. You will also learn basic guidelines on how to write cleaner code.

Who is a Professional?

“Writing clean code is what you must do in order to call yourself a professional.”

Several years ago, I hired a cleaning lady. She was a true professional. She paid attention to every detail of her work; she took pride in it. Sometimes, she worked past the time she was to go home to finish her job completely.  

“The mark of a true professional is attention to detail.”

Being a professional has nothing to do with the work and everything to do with the attitude towards the work. In contrast to my professional cleaning lady, as a teacher in my previous life, I worked with some teachers who were not professionals. They did not put much effort to create beautiful lessons. They did not pay attention to who was focused in their class, who was learning, and who had difficulties. Their work was a job, not a profession. 

 “We are honest about the state of our code because code is never perfect.”

A professional pays attention to the details that seem small if you look at them by themselves, but the accumulation of these details makes a significant difference in the quality of the work. In my opinion, this attention to detail is what separates a professional from a wage earner. A wage earner does the job. A professional does the job with care, attention to detail and the knowledge that there is always room for improvement. 

What is Clean Code?

“Clean code is code that is read like a well-written prose.”     

Photo by Markus Spiske

Clean code is a pleasure to read. Like a good book, your code has to be clear. All parts of it have to make sense. There has to be a story to it that is understandable.  The job is not only to write code that works but also to write code that can be read and understood with ease and with pleasure. 

“Getting software to work and making software clean are two very different activities. Too many of us think that we are done once the program works. We fail to switch to the other concern of organization and cleanliness. We move on to the next problem rather than going back.”

As a developer, we have two very different jobs: Making software work and making software clean. Our job is not finished once our code works. That would be like saying that the job of the restaurant chef is finished when the meal is cooked. It is not finished. Now, he has to take the food out of the pot, arrange it beautifully on a plate and add the details to make the food appealing to the customer.

“We should view our code as the beautiful articulation of noble efforts of design — design as a process, not a static endpoint.”

Once the software works, we need to clean it. We need to prepare it for the reader. It has to be organized and clear. It has to read like a beautiful novel, all pieces fitting together in the right place, at the right time. The writer of a novel spends most of her time rewriting. Cleaning code means rewriting your code to make it better.          

Why Should We Write Clean Code?

“In software, 80% or more of what we do is maintenance.”

Photo by Clément Hélardot

Most of what we do as developers is maintaining code that we have or someone else has already written. Making your code easy to understand is essential to making your code easy to maintain. That’s why writing clean code is so important. Other developers or you, yourself, have to maintain it. To maintain it, you have to understand it. If your code is hard to understand, it will be hard to maintain.

How to Write Clean Code

“You are reading this book for two reasons. First, you are a programmer. Second, you want to be a better programmer.”

Here are some rules to keep in mind, while writing and especially while rewriting your code to clean it.

Rules about Functions

“The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that.”

Each function is part of the story that your code tries to tell. Write small functions that have only one job. This will make your code easier to understand and also easier to enhance. Break down a large function into smaller functions. 

“Functions should do one thing. They should do it well. They should do it only.”

Rules about Classes

“A system with many small classes has no more moving parts than a system with a few large classes. The question is: Do you want your tools organized into toolboxes with many small drawers each containing well-defined and well-labeled components? Or do you want a few drawers that you just toss everything into?”

Like functions, your program should be made of small classes, each with only one responsibility. If you have a hard time figuring out a name for a class, it may be because the class has more than one responsibility. Break it down.

“The first rule of classes is that they should be small. The second rule of classes is that they should be smaller than that.”

Naming Rules

“Choosing good names takes time but saves more than it takes.”

Finding good names for your variables, functions and classes can go a long way towards making your code readable and understandable. If a name you picked requires using a comment to explain it, pick a better name.

Variable Names

“You should name a variable using the same care with which you name your first-born child.”

Variable names should be descriptive. The reader should understand exactly what the variable is, just by its name. The length of the name does not matter. The clarity of the name is what matters. Here are examples of good variable names:

  • elapsed_time_in_days
  • seconds_since_creation
  • number_of_tasks

Function Names

The name of the function should explain what the function does. Pick names for functions in the format of a verb because functions do something. Verbs show action. Here are examples of good function names:

  • print_game_board
  • email_stock_message
  • display_search_results

Class Names

Like functions, the name of the class should describe its responsibility. Classes don’t identify actions. So, class names must be in the format of a noun. We use nouns to refer to objects, people, animals, or places. Here are examples of good class names:

  • Customer
  • Account
  • Vehicle

Formatting Rules

“Clean code always looks like it was written by someone who cares.”

Photo by Danial Igdery

Keep the reader in mind when formatting your code. Is reading your code easy on the eye? Does the formatting help tell the story of your code? Think of a newspaper article. Lead the reader from the most important part of your code to the least important. Here are a few formatting ideas directly from the book:

  1. “Use white space to separate different aspects of your code.”
  2. “The most important functions should come first.”
  3. “Lines of code that are closely related should be closer together.”
  4. “Variables should be declared as close to their usage as possible.”
  5. “If one function calls the other, they should be close. The caller should be above the callee.”

The One Rule about Writing Comments

“The only truly good comment is the comment you found a way not to write.”

Put all efforts to make your code understandable without comments. Make your code speak. Sometimes, all you have to do is to pick better names. Sometimes, you have to rework your functions, or rearrange where they appear in your code. Do all you can not to write a single comment. 

Small Things Matter

“That these acts are simple doesn’t mean that they are simplistic, and it hardly means that they are easy.”

Photo by Agê Barros

You will not become an expert at writing clean code by reading an article or a book, but over time, if you are dedicated to it, you will get better. The result of your efforts will be the products you can be proud of — products others will appreciate. 

“Learning to write clean code is hard work. You must sweat over it. You must practice it, and watch yourself fail. You must watch others fail.”

The Art of Clean Code

Most software developers waste thousands of hours working with overly complex code. The eight core principles in The Art of Clean Coding will teach you how to write clear, maintainable code without compromising functionality. The book’s guiding principle is simplicity: reduce and simplify, then reinvest energy in the important parts to save you countless hours and ease the often onerous task of code maintenance.

  1. Concentrate on the important stuff with the 80/20 principle — focus on the 20% of your code that matters most
  2. Avoid coding in isolation: create a minimum viable product to get early feedback
  3. Write code cleanly and simply to eliminate clutter 
  4. Avoid premature optimization that risks over-complicating code 
  5. Balance your goals, capacity, and feedback to achieve the productive state of Flow
  6. Apply the Do One Thing Well philosophy to vastly improve functionality
  7. Design efficient user interfaces with the Less is More principle
  8. Tie your new skills together into one unifying principle: Focus

The Python-based The Art of Clean Coding is suitable for programmers at any level, with ideas presented in a language-agnostic manner.