Clean Code, a definition (essay)

Important note – TDD discussions are deliberately out of scope, to be discussed later, because of the complexity of the subjects.

NO ACCURATE DEFINITION. Can be accurate? Perhaps not. We need a good enough definition. What we have now are not definitions, but rather descriptions about Clean Code attributes. At the end of this post, you can find the thoughts of some well-known programmers interviewed by Robert C. Martin for the book “Clean Code”.

SCHOOLS OF THOUGHT.  Also, there are some different “schools” of thoughts related to this part of software design. Quoting from Robert C. Martin, from the same “Clean Code” book (“Schools of Thought”): 

“None of these different schools is absolutely right. Yet within a particular school we act as though the teachings and techniques are right. After all, there is a right way to practice Hakkoryu Jiu Jitsu, or Jeet Kune Do. But this rightness within a school does not invalidate the teachings of a different school.” 

“Consider this book a description of the Object Mentor School of Clean Code. The techniques and teachings within are the way that we practice our art.” 

Clean Code & Refactoring are not “invented” by Robert C. Martin, Martin Fowler, Kent Beck and their collaborators. This is rather a category of software design where are more significant contributions. Examples of books: “Clean Code” (by The Object Mentors:Robert C. Martin, Michael C. Feathers Timothy R. Ottinger, Jeffrey J. Langr Brett L. Schuchert, James W. Grenning Kevin Dean Wampler), “Refactoring” book (by Martin Fowler, Kent Beck, John Brant, William Opdyke, Don Roberts),  “Pragmatic Programmer” (by Andrew Hunt David Thomas),  “Code Complete” (by Steve McConnell), “Implementation patterns” (Kent Beck).

CLEAN CODE AND REFACTORING. In fact, using other names, we have similar guidance from other authors, before or after the book “Clean Code”. The first name that comes to my mind is “Refactoring” book (by Martin Fowler, Kent Beck, John Brant, William Opdyke, Don Roberts). In fact, we refactor to a cleaner code. Paying the technical debt (refactoring) too late and for huge amount of debt it is a waste: we need to stop the other works and it is a huge effort.  It is much better to learn how too write clean code and to refactor early (… we already know that if we know how to refactor, but we need to share the expertise with the whole team).

ATTRIBUTES. Here some attributes of the Clean Code that are more often mentioned: simple, easy to read (also by the others), meaningful names, straightforward, designer’s intent is clear, no duplication, each part do what you expected.

TIMING. As you see these attributes are rather generic aspects, not particular design patterns. In the same time, as opposed to some design patterns as Observer, Template, Adapter, MVC or architectural patterns as Pipes and Filters, Microservices, the “patterns” related to Clean Code are small, and are used much more often. Clean Code it is used to refer all kind of design decisions from smaller one to architecture, but in practice, the authors or experienced engineers talk mostly about the ones that are small, generic and are used very often.

A good programmer will do some refactoring daily and very often during every day, for both legacy and new code. How much refactoring and which the refactoring principles and patterns will be used? That depends on the context. What we can observe is that a good programmer will use refactoring very often. Sometime the same programmer could write a good enough code from the first time.

How many times in a day we are deciding about naming, functions responsibilities or about how clear we express intents in the code for us and for other? Very often! How often we will use a particular “big” design or architectural pattern? No so often. We cannot decide to use refactoring or clean code only later, in the next release, next product or next month. We will rather use them daily. Not all the rules, not always, we will still need to decide where, what and how. We can combine various sources and we are free to innovate.

Figure 1 - Design Decisions Timing Pyramid

WHAT IS CLEAN CODE?  It is a set of principles & practices for getting a good software design that are rather generic and are applied to some categories of design decisions that occur very often.

CLEAN CODE IN CONTEXT. Each design decision must consider the opportunity in context. Decisions about applying these principles & practices are still related to context, that including also the necessary “amount of care”. In some cases, such building a small throw-away prototype we could spend less time and consume less effort on getting the code clean, but we will still do it because we still need to read the code and we need to not get false-positive or false-negative answers caused by messy code.

IMPACT OF THE CLEAN CODE/MESSY CODE.  We take a lot of small design decisions each day, each hour and each minute. All these rather small decisions will massively influence our product design and architecture, our product technical debt. This a cumulative process. If we check the code of a software product that is hard & change with symptoms like fragility, rigidity, viscosity, we will find un-necessary complexity related to messy code.

IMPACT ON USAGE. A messy code with a lot of technical debt will have more bugs, bugs will be much harder to fix, changes will be harder to perform and more expensive. Depending on the criticality of the target system we will need a different “minimum amount of care” related to the software design. Also, similar problems could have a  much different impact in a different context.

IMPACT FOR DEVELOPMENT. Beyond repercussions resulted from the impact at usage, we will have a direct impact for development side. Simple, clean and adaptive code:    

• Contribute to better software economics for development side: easy and less expensive to build and change the software products.
• Increase the comfort (and decrease the stress) for the other developers that need to read, understand and change that code

A code with high technical debt that harms the development business will also harm the people that work for that business (beyond comfort, they could lose money or even their jobs).

INDUSTRY LEVEL PROBLEMS. One of the main problems of the software industry is the unnecessary, undesired complexity with all known resulted problems. Software development has as main traits: complexity, incertitude and knowledge work. Considering this generic context of the domain, we want to avoid producing unnecessary complexity by massive accumulation of technical.  Developers, teams, organizations need skills to manage this technical debt and keep it down in an appropriate way for the needs of target business but also for the needs of development side.

WE NEED CLEANER CODE. Software will rule the world. All aspects of our lives will be highly dependent on software. The software industry is growing, the number of developers is growing fast, but the necessary skills for avoiding big problems on software usage are not appropriate. The produced software is too messy to meet these needs. The software community must react and must reduce this unnecessary complexity of the software design.  

(LEARNING) HOW TO MAKE A CLEANER CODE. How do we learn refactoring and clean code? Can we select in which releases, components or products we will use them and in which we will not? Can we learn them for the next release? It is like a basketball player will train for running or for shooting only for specific games or competitions. You will always train, and you will always use them, but is your decision and your team decision how you will combine running, shooting and dribbling. You cannot learn how to build clean code or how-to refactor if that is not a long-term ongoing & collaborative activity.

 

HUMAN FACTOR ON CLEAN CODE. Clean code is a result of the whole team work. Each developer will take clean code/messy code decisions in every minute. If 20 developers produce messy code and 1-2 will occasionally clean & refactor, that is waste. Knowledge about refactoring and building a cleaner code must be shared between team members in many ways, but especially by collaborative work. More: one of the main benefits of the collaborative work will be cleaner code. Even senior developers will produce much cleaner code and better design if they learn from their colleagues. More, by helping others, you will understand which kind of design is more effective for working in a team.

CLEAN CODE AND TEAM WORK. One of the goals of clean code is to make the code readable for your team. Your colleagues will be able to understand and change your code. The existent code is an inherent source of learning for newer team members and juniors: you want to provide them good examples.

CLEAN CODE AND PRODUCT. The cleanness of the code (also by refactoring) massively contributes the design quality status of our product. We want a product that is easy to change? Keep it clean enough. We want quality? Keep it clean enough for the context.  We want agility? If the code is not clean enough forget about that.

CLEAN CODE IS ABOUT CARING. If you care about: your colleagues (to use your work, to learn, to have a job), your products and your company (better software economic: you can easily change the products), your customers (to avoid possible disastrous effects of messy code), then please keep your code clean. If you care about the effects of “software will rule the world” then collaborate with software community to improve the techniques & practices for making the code cleaner.    

PROGRAMMERS ABOUT CLEAN CODE

For “Clean Code” book Robert C. Martin “ask some very well-known and deeply experienced programmers what they thought”. Here are extracts from their responses

Bjarne Stroustrup: “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.”     

Grady Booch: “Clean code is simple and direct. Clean code reads like well-written prose. Clean code never obscures the designer’s intent but rather is full of crisp abstractions and straightforward lines of control.”

Dave Thomas: “Clean code can be read and enhanced by a developer other than its original author. It has unit and acceptance tests. It has meaningful names. It provides one way rather than many ways for doing one thing. It has minimal dependencies, which are explicitly defined and provides a clear and minimal API. Code should be literate since depending on the language, not all necessary information can be expressed clearly in code alone.”

Michael Feathers: “I could list all of the qualities that I notice in clean code, but there is one overarching quality that leads to all of them. Clean code always looks like it was written by someone who cares. (my note: this is my favorite description) There is nothing obvious that you can do to make it better. All of those things were thought about by the code’s author, and if you try to imagine improvements, you’re led back to where you are, sitting in appreciation of the code someone left for you—code left by someone who cares deeply about the craft.”

Ron Jeffries: “In recent years I begin, and nearly end, with Beck’s rules of simple code. In priority order, simple code:

•       Runs all the tests;

•       Contains no duplication; 

·        Expresses all the design ideas that are in the system;

•       Minimizes the number of entities such as classes

methods, functions, and the like.

Of these, I focus mostly on duplication. When the same thing is done over and over, it’s a sign that there is an idea in our mind that is not well represented in the code. I try to figure out what it is. Then I try to express that idea more clearly. […] “

Ward Cunningham: “You know you are working on clean code when each routine you read turns out to be pretty much what you expected. You can call it beautiful code when the code also makes it look like the language was made for the problem.”

BIBLIOGRAPHY , REFERENCES

• Clean Code: A Handbook of Agile Software Craftsmanship 1st Edition ,by Robert C. Martin (The Object Mentors:Robert C. Martin, Michael C. Feathers Timothy R. Ottinger, Jeffrey J. Langr Brett L. Schuchert, James W. Grenning Kevin Dean Wampler), Prentice Hall; 1 edition (August 11, 2008)
• Refactoring: Improving the Design of Existing Code 1st Edition, by Martin Fowler (Author), Kent Beck (Author), John Brant (Author), Addison-Wesley Professional; 1 edition (July 8, 1999)
• Implementation Patterns 1st Edition , by Kent Beck, Addison-Wesley Professional; 1 edition (November 2, 2007)
• The Pragmatic Programmer: From Journeyman to Master 1st Edition
  by Andrew Hunt , David Thomas  , Addison-Wesley Professional; 1 edition (October 30, 1999)
• Code Complete: A Practical Handbook of Software Construction, Second Edition 2nd Edition, by Steve McConnell  Microsoft Press; 2nd edition (June 19, 2004)