Writing Clean Code in First Attempt

Table of Contents

In 10 years of my journey from a developer to an engineering manager, I have been part of many product teams in different domains and with a variety of technical needs. In this diversity, I feel there is one common unsaid requirement, the code must be clean and readable.

So why clean and readable code?

“Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. …[Therefore,] making it easy to read makes it easier to write.“ ― Robert C. Martin

But how do you write clean code? Is there a process you can follow?

Every time I think about these questions, It leads me to this article explaining writing process.

The Writing Process

Writing evolves every time you read. Similarly I think every piece of code will have room to improve. Practically, one logic can be transformed into piece of code in many different ways, some ways are cleaner and some requires further iteration.

I believe writing an email, a book, a blog or even a piece of code should follow the same process. The only change is the context.

So let us see how 5 steps for writing clearly can be contextually applied to write clean code.

Planning

First thing first, Planning is a must for writing code or an article.

“Planning may fail, but that doesn’t mean not to plan. Hours of planning can save you weeks of programming” – Unknown

1) Understand Requirements

The most important thing is to plan a code for the user that does the job. So to understand captured user’s perspective quickly and simply in form of user story is the way to start. One should involve user by understanding requirements in following format.

As a < type of user >, I want < some goal > so that < some reason >.

An example,

As a Restaurant Manager, I should be able to see daily stock details of ingredients so that I can plan for next day purchase.

This will give immense clarity on what code needs to do for the user.

2) Impact Analysis

Impact analysis at code planning level is to identify the code area that will be directly and indirectly affected. This will give you better idea of what all is involved..

3) High level pseudocoding

Pseudo-coding is very less popular practice among developers, but it is the most powerful technique to build rough sketch of code during planning. Expresses the intent as clearly as possible and allow the coder to focus on the novel parts of the algorithm

Drafting / Writing Code

During Drafting an article one starts putting his/her thoughts on paper in form of vocabulary. Similarly writing code is putting your thoughts in form of code into editor. You can include best practices but more important is to put all your thoughts in form of code and make brain empty.

Bad code does too much – Clean code is focused.

So remember the golden rule – “Every piece of code must do one thing only”

What you should NEVER do is copy a library function or existing piece of code that you don’t know what EXACTLY it does.

Write test cases, plan for TDD but on a coarser level because testing at unit level is not serving the purpose. 100% Coverage should not be the goal. Check out this excellent keynote by DHH at RailsConf 2014 explaining how TDD should be perceived.

Revising/Iterating

The goal of revision is to make code more clean, readable and efficient.

Most of the developers find revision a redundant task but if you do not revise you will never improve. You can revise your code any number of times. This is mainly done by applying best practices like exception handling, selecting right data types, memory management, caching, and optimization, etc.

Make sure the core objective of writing piece of code remains intact and bug free.

Editing

You can checkout piece of code for naming conventions. Variables, Functions, Class Names, Folder Structure, etc should be spelled correctly. It should depict its usage.

Let me tell you how much naming a variable is important.

“You should name a variable using the same care with which you name a first-born child.” ― Robert C. Martin

Well, he is not asking you to involve your spouse in naming a variable but you get the drill!

Remove unnecessary and temporary code and make sure the Debugging mechanism is turned off.

Formatting

Thankfully, we have good editors that provides code beautification. With just one key combination it will format it all. This is much simpler for a developer as compared to a article writer.

Writing is about clarity. Writing is about presenting information in clear manner. We can write with small words, with little complications to get job done.

It becomes very easy when you think about writing code is not science but is more of art. If you follow this simple process and practice it you are sure to become a far better programmer.

What is the process you follow to write clean code?