What is Clean Code?

Clean Code Development

While the early works of Robert C. Martin “Clean Code: A Handbook of Agile Software Craftsmanship”² or Dustin Boswell “The Art of Readable Code”³ focused primarily on the simple, textual form of code, the Clean Code Developer School takes a broader approach: it looks at the development process and defines values and numerous principles and practices. Above all, however, it recognises that an agile approach and structural considerations before implementation – namely analysis and design – are necessary. Without an appropriate structure, the implementation of non-functional requirements is very difficult or even impossible.

Furthermore, the structure of a software provides the basis for an evolution based on new requirements. Without structure, the costs for new features increase exponentially. In addition, it is difficult to add a structure at a later stage. In the course of Clean Code Development, the saying applies: First the analysis and design, then the implementation. Or, to put it another way: first think cleanly, then implement cleanly.

Clean Code Values

The approach to implementing clean code is based on a foundation of four values:

• Changeability
• Correctness
• Production Efficiency
• Continuous Improvement

Correctness

Correctness as a value may sound banal at first. But there is more behind it than just the correct execution of functions, the correct use of classes and methods, or the application of principles and practices of software development. Correctness also addresses the handling of requirements.

Often developers do not even know the requirements of customers. They do not know any acceptance criteria. They do not know any framework conditions or the system context, no application scenarios and no non-functional requirements. How can one succeed in paying attention to correctness? Instead of trusting (or hoping) that a test department will find possible errors, developers should understand what customers actually want before implementation. Only when they know this can they implement applications correctly.

Continuous Improvement

The value “continuous improvement” does not address the improvement of the implementation as such, because this aspect is already part of the evolvability. The continuous improvement requires the developers to deal with their way of working. For example, the following questions could come into focus:

• What experiences were made with pair programming or mob programming?
• What are the causes of code smells?
• How can the cooperation within the team and with customers be improved?
• What are our learnings in code reviews?
• What should be improved in the next iteration?
• How can code katas be optimised?

Continuous improvement is therefore a value that revolves around the reflection of the team.

Which of these values should developers look for first? Primarily, the values are not in an explicit order that developers can follow. One value is not more important than another. Nevertheless, changeability is consciously the first priority. It stands for a basic attitude, an openness to future requirements and evolutions, even if these are of course not yet known. Just as Safety First applies in aviation, changeability should be the first thing that applies in software development.⁴

Clean Code Principles and Practices

Even if the values provide orientation for software developers, they are too abstract for concrete implementation. That is why there are principles and practices:

• Principles are guidelines for structuring software. They complement each other. Ideally, a maximum number of principles is always observed. If software is developed contrary to these principles, the effects will become apparent in the medium term at the latest, for example, through increasing costs for adjustments. An implementation tends to reveal whether a principle has been observed or not.
• Practices are instructions for action. They are methods and techniques that are used continuously. Some practices require the use of tools. And it is not always possible to recognise from the implementation whether a practice has been implemented or not.

Below you will find an overview of the principles:

KISS – Keep It Simple and Stupid

“Make it as simple as possible” the KISS principle says. It demands not to see or implement things too complicated, and always to look for or use the simplest solution to a problem.

FCoI – Favour Composition over Inheritance

The FCoI principle propagates the use of compositions instead of inheritances, so that classes are separated from their algorithms and their details in order to be able to change the behaviour of a class at runtime.

SLA – Single Level of Abstraction

The SLA principle states that different levels of abstraction of functions should not be mixed in order to increase the readability, understandability and maintainability of the code.

SoC – Separation of Concerns

The SoC principle calls for a class to concentrate on a specific aspect in order to be able to test individual concerns separately and to make adjustments in a manageable way.

ISP – Interface Segregation Principle

The ISP principle states that interfaces have a high degree of cohesion and should therefore only contain elements that belong together. The aim is to make the coupling between components “lean” and clear.

LSP – Liskov Substitution Principle

The CSP principle states that derived subtypes must behave like their basic types, whereby subtypes may extend the functionalities of the basic types but not restrict them.

Information Hiding Principle

According to the information hiding principle, the inner workings of components should be encapsulated or hidden by interfaces in order to avoid unnecessary dependencies and extensive adjustments.

TDA – Tell, Don’t Ask Principle

The TDA principle is about bundling data with the functions that work with this data. Instead of asking an object for data in order to act with this data, the object should be told what it should do.

Implementation Reflects Design

Implementation should not exist independently of design or architecture. For example, components defined in the architecture should also be physically separated in the code.

YAGNI – You Ain’t Gonna Need It

The YAGNI principle demands that functionality is only implemented when it is actually needed. Often requirements for features are still too imprecise or they turn out to be unnecessary later. In case of doubt (premature, unnecessary) efforts should therefore be avoided.

Together, the Single Responsibility Principle, the Open Closed Principle, the Liskov Substitution Principle, the Interface Segregation Principle and the Dependency Inversion Principle are also known as the SOLID Principle. In his book “Agile Software Development: Principles, Patterns and Practices” Robert C. Martin considers these principles to be essential for the development of clean code.⁵

Below you will find an overview of the practices:

Carry Out a Root Cause Analysis

Root Cause Analysis focuses on the elimination of causes rather than the elimination of symptoms. This is much more efficient in the medium term.

Apply Simple Refactoring Patterns

Refactoring addresses the restructuring of a software while retaining the range of functions. Extracting methods or renaming incomprehensible names are simple refactoring patterns.

Issue Tracking

Issue Tracking, also known as Bug Tracking, describes the process from the recording to the elimination of bugs, open issues, requests etc.

Conduct Reviews

Reviews increase the quality of the code, whether in the course of pair programming, peer reviews or code reviews. The aim is the continuous improvement of the code quality.

Use Automated Unit Tests

Unit tests check whether the developed components work as intended. For example, individual classes or methods are tested. The automation of the tests reduces the test effort.

Analyse Code Coverage

Code coverage expresses what part of the source code – statements, branches, paths and conditions – is executed by test cases. The aim is to find the parts that are not yet tested.

Take Part in Professional Events

In order to educate yourself in the field of software development, in addition to reading technical literature, it is important to exchange ideas with other developers – for example at meetings, in user groups or at conventions.

Collect Metrics

Static code analysis helps, for example, to check correctness by means of automated tests or to determine compliance with requirements. The changeability of a software can also be partially determined by metrics.

Pass on Experience

Having knowledge is good, passing on knowledge is very good. The idea behind it: only through the transfer of knowledge does true reflection and the penetration of a specialist topic take place. And everyone involved benefits from this.

Pursue Continuous Delivery

Continuous Delivery describes a process for the delivery of tested updates, in which setup and deployment are automated. It follows after the Continuous Integration.

Develop in a component-oriented way

Component-oriented development promotes productivity through parallel implementation, improves the clarity of the application and facilitates testing of the individual components.

Test first

Test first propagates that interfaces and a correspondingly desired behaviour are described by tests. This approach simultaneously produces specification documentation in the form of executable code that can be automatically checked.

Tips for Using Clean Code

And how do values, principles and practices come together? What are the tips for implementing Clean Code?⁷

• General tips
  Follow the conventions. Reduce complexity as much as possible. The simpler the code, the better. Act like a boy scout and leave the code better than you found it. And always look for the cause and not the symptom of a problem.
• Design tips
  Keep configurable data at a high level. Use polymorphism instead of if/else or switch/case. Use separate multithreading code. Avoid over-configurability and use dependency injection. Follow the Law of Demeter.
• Tips for comprehensibility
  Be consistent and implement similar things in the same way. Use explanatory variables. Encapsulate boundary conditions, as they are often difficult to understand. Prefer dedicated value objects over primitive types. Avoid logical dependencies, e.g. do not write methods that work correctly depending on something else in the same class. And avoid negative conditions.
• Tips for names
  Use descriptive, unambiguous, meaningful, pronounceable and searchable names. Replace magic numbers with named constants and avoid encodings.
• Tips for functions
  Keep functions small by doing just one thing. Use descriptive names and use as few arguments as possible. Avoid side effects.
• Tips for comments
  Try to let the code speak for itself. Do not comment on your code. If you do comment, do it to explain the intention or to point out possible side effects.
• Tips on the structure of the source code
  Declare variables near their usage. Dependent and similar functions should be close together. Place functions in a downward direction, avoid horizontal alignment. Keep lines of code short, use white spaces to associate or disassociate aspects and use on indentations.
• Tips for tests
  Make tests readable, fast, independent, repeatable and automated. And only test one aspect per test at a time.

Challenges in clean code development

Changeability, correctness, production efficiency and continuous improvement are the four values of Clean Code. To postulate them as advantages or goals sounds logical and sensible, but in the reality of software development the implementation is anything but easy. Clean code cannot be easily measured and therefore cannot be implemented in passing. This is where the principles and practices come into play. However, this is combined with the willingness to continuously deal with clean code, its meaning and its concrete implementation. Only if the focus is on clean implementation can it succeed in the long term. In this case less is actually less and more is actually more. In modification of one of the principles one could say: You gonna need it!

• Is clean code more important than / equally important as / less important than functional or performant code?
• Can clean code be developed at all?
• Do companies actually pay for clean code or rather for its absence?

Notes (some of them in German):

[1] Here you will find information about the Clean Code Developer School and its view on sustainable productivity in software development.
[2] Robert C. Martin: Clean Code: A Handbook of Agile Software Craftsmanship
[3] Dustin Boswell: The Art of Readable Code: Simple an Practical Techniques for Writing Better Code
[4] Die Clean Code Developer School: Die Anforderungen auf die Füße stellen
[5] Robert C. Martin: Agile Software Development: Principles, Patterns and Practices
[6] Martin Fowler: Online Catalog of Refactorings
[7] Wojtek Lukaszuk: Summary of tips

In 2008, Robert C. Martin propagated a 5th value at a conference: We value craftsmanship over crap. Martin had observed that both Extreme Programming and Scrum would not eliminate central problems of development and called on those present at the conference to write Clean Code from now on and not to bow to time pressure or claim that they did not have time for it or were not allowed to do so.

Here you can find additional information from the t2informatik Blog:

t2informatik develops and modernises software as a service provider. Click here to learn more.