Notes on “Clean Code”​ — How to Care for Code?

Original article was published by Mohamed El-Geish on Artificial Intelligence on Medium


Notes on “Clean Code”​ — How to Care for Code?

An AI-Rewrite of My LinkedIn Article With the Same Title & Introduction

Photo Credit: Mohit Suthar from Pexels

Disclaimer: This article was written mostly by GPT-3 given the introduction of my original article as a prompt; a few edits were made.

A French philosopher, by the name of Guillaume Ferrero, discovered the Principle of Least Effort and wrote about it in 1894 — long before a single line of computer code, as we know it today, was written. Nevertheless, I can’t help but think that, had he been alive to witness how most code is written, he would have demonstrated coding as the epitome of the least effort principle:

[Coding] stops as soon as minimally acceptable results are found.

I think the idea of just getting it done is a plague in today’s software world. I don’t know whether it is a symptom of our trying to cram way too much work into our lives since we don’t take enough time to work at our craft or if there is something fundamentally wrong with how we think about time and work, but the idea of just getting it done seems entirely antithetical to the idea of software craftsmanship. I don’t know how we, as a software community, can move beyond that. I, for one, do know how I can move beyond that, though.

I think it has to do, mainly, with leadership. I don’t mean management per se—you too can be a leader even if you’re not a manager. Just talk to your teammates; tell them that you are opting out of this race to the bottom and that, if they have any interest in improving their craft and taking ownership over their professional lives, they should do the same. If you need help, invite them to read this article and, better yet, Clean Code. My hope is that, by the time they are done reading, they will have a better idea of what it means to be a software craftsman and will have learned the necessary skills to help them start making the world a better place by doing good software. I do want to share some of my thoughts on how to create the least effort necessary to deliver the most value; and doing it all “the right way”. If you are interested in the topic of software craftsmanship, I’d recommend reading the rest of this article. If you are not, it’s still worth reading because it’s a lot of fun.

Back to the Principle of Least Effort; in order to expand on this concept, let’s break it down. Least, by definition, means the smallest or the smallest known quantity. In the context of software, it is the effort needed to produce the minimum acceptable results. The effort needed to achieve the minimum acceptable results can be described by two things: How easy it is to produce the solution. How good the solution is, compared to the ‘perfect’ solution.

Good solutions can be measured on a scale from 0 to 10, with 0 being an extremely poor solution that is unacceptable and 10 being the perfect solution. The effort to achieve a point on this scale is a tradeoff between time and quality. For example, a solution that takes 2 days to build, but has a score of 5, can be described as a 2/5 solution. This is an acceptable solution. The ideal solution would be a 10/10 solution that takes no time to build. This is unrealistic, of course. As you can see in the example above, it’s far easier to measure time than it is to measure quality.

Since software is a measure of both time and quality, it’s not possible to measure the least effort in software. The only thing we can do is to compare the cost of a solution, and compare it to the value it provides to the business. The higher the value, the better the solution. The same concept can be applied to the other side of the scale as well. If the effort to produce a solution is low, but the quality is low as well, the overall solution is still low. With this in mind, we can apply the Principle of Least Effort to software. How do we make our software as easy as possible to build, while balancing the cost of effort with the value it provides to the business?

One approach is to follow the principle of Test Driven Development (TDD). TDD is a practice where developers write their tests first, then write the code to make the test pass, and finally refactor the code. This practice forces the developer to think about what they’re building before they build it. During this process, the developer is aligning with the business and the customer, as well as ensuring the product is built in the right way, the first time.

Another principle to follow is High Cohesion, Low Coupling; for that, we need some definitions. I will be using these definitions in this article: In olden times, Agile teams would say that they wanted to be “high cohesion, low coupling”. Nobody knew what this meant, but everybody on the Agile team sang it like a mantra. One day, I read a definition that helped me really understand what this principle means:

High Cohesion means that you have code that belongs together bundled as such; Low Coupling means that you have as few dependencies as possible among bundles.

Now that we have a common definition, let’s look at the two principles above and how they can help with software craftsmanship. The first principle — TDD — is one of the best practices of Extreme Programming (XP). It has been shown over and over again to produce the best results, and it is currently one of the best practices for building software. This is the first principle: we write our tests first, and we’ll be able to write our code in a way that will align with the business, and provide the best solution. The second principle is: when we are building software, we are building a solution that is going to be used by others (and our future selves). We have to make sure that our solution is as independent as possible, and that it does not rely on any other solution to work. This is how we achieve high cohesion, and low coupling. The level to which we achieve high cohesion and low coupling is called the level of abstraction. When we achieve high cohesion and low coupling, we achieve a high level of abstraction. This is the goal: We care for our code by making it work well for the business that’s going to use it, and by caring for those who are going to work on in the future. We need to focus on writing code that is easy to write, easy to read, and easy to maintain—that’s how we care for code.