Python for Beginners

Writing Clean Code – Part 1

Introduction

This is the first part of a 3-part lesson on writing clean code. During this lesson we
plan to discuss the need of clean code, the main qualities of a clean codebase and 5
techniques which help the developer write clean code on a day to basis.

Color Coding

Following color code is used throughout the presentation.

Evolution of a Codebase over Time

To understand the need of Clean Code, one must understand how a Code Base and
a Software Project evolves over time.

As this diagram explains, a team of developers would start writing code with a new
set of features or requirements to realize these requirements as software. Once
coding is done, the code must be tested to ensure everything works as expected.
At this point the code could be considered as stable and the team would mark this
version of the code as stable using version controlling. Git is a good option for
version controlling.

With time, more features, improvements and defect fixes would come into existence.
To apply these to the existing code, the developers would write code, test the code,
mark the working and stable version. This cycle continues until the software
continues to evolve.

It’s important to note that writing code is not limited to adding new code. Changing
and removing code also plays a major part in creating software. Writing new code is
relatively easier since the developers exactly know what to be coded. However,
changing and removing code needs a very good understanding of the existing code.

Evolution of Famous Codebases

The table above showcases how the codebase changed for some of the famous
software in the world. All of them have done many releases. A release is where the
software project team do significant code changes to implement new features,
enhancements or bug fixes, test the code and provide it to be used by the general
public.

This proves that codebases of the software that are used frequently, grow in size
(i.e., lines of code increase) and they keep on changing and will continue to change
in the future.
Evolution of a Software Project Team with Time

Initially the team would be smaller. With time when more new features,
enhancements and bug fixes come into existence, new team members must be
injected to the team to manage the increasing workload. Even if the team size does
not increase, it’s natural that some existing team members who have a good
understanding of the codebases decides to leave the team. In such cases, the
vacancies must be filled by new team members.

The new team members who do not have a good understanding of the existing
codebase must be brought up to speed to ensure the work gets done and delivered
on time. Usually, the existing team members organize knowledge transfer sessions
where they walk the new team members through on the codebase and discuss logic
and how the code is constructed. With this understanding the newcomers are
expected to start reading code on their own to strengthen their understanding.

Tension in Knowledge Transfer Sessions

If the code is not clean, it’s difficult to read and understand. Hence, the knowledge
transferring sessions could be tensed, frustrating and time wasting for both old and
new team members.

Therefore, having a clean codebase makes it easier to understand and allows the
team to manage change smoothly

Clean Code – Definition from Grady Booch

Following are the main characteristics of a Clean Codebase that can be extracted
from the definition of Clean Code provided by Grady Booch;

1. Simple and direct

2. Has a nice flow like a well-written story

3. Doesn’t hide the developer’s intention.

4. Summarizes intention without ambiguity

If the codebase is aligned with the above characteristics, the codebase would hold
the following qualities.

1. Easier to understand

2. Easier to change

3. Easier to test

4. Easier to add features without changing code

Clean Code Mindset

Readability, Maintainability, Testability and Extensibility are the four main traits of
Clean Code. Each of these traits discuss a unique aspect of Clean Code.

It’s extremely important that any developer who wishes to write Cleaner Code aligns
his or her mindset on the four main traits of Clean Code. The best time to align the
code to the above qualities is at the time when the code is written for the first time.
This is the time where developers have the best understanding of the code and it’s
easier to apply best practices. Delaying the code cleanup activities may result in the
code cleanup not happening at all due to other competing priorities.