Don’t be a half-witted, nerf herder. Or what is Clean Code?

Our team is reading through the classic Clean Code together. After reading a chapter or two we will get together to discuss the concepts over lunch. We try to keep them fun and interactive. These are the slides from our first session (link).

In discussing the question – why don’t we write clean code – we explored the following three reasons.

There is a level of subjectivity

There is a good chance that when I opened a pull request for my team to evaluate, I thought the code being pushed read like well written prose, was understandable to others, tested, and was thus maintainable by my colleagues. However, the code should be considered readable by the team that is responsible for owning and maintaining it. Which usually means that there will be some comments and feedback.

mycode

There may not be an understanding of what Clean Code is

If writing clean code was obvious I imagine that Bob Marin would not have written a book on it. And sites , like the Daily WTF, poking fun at various “dirty” code would not exist. Understanding what clean code looks like and the techniques to improve it must be learned. Our goal as a team is to work through Clean Code so everyone on the team will know what clean code is and why it is important.

how-does-that-work

There was a deadline to meet so there wasn’t any time

Perhaps the most common excuse for why “dirty” code is accepted and deployed is because the team rushed to put something together to meet a deadline. Unfortunately, that means that we now have to make time to not only add new features, but also go back and clean up the mess we made.

no-time

Bob Martin pushes back on the deadline excuse, noting:

The only way to make the deadline – the only way to go fast – is to keep the code as clean as possible at all times.

Quality is not a product variable

When I was exposed to Agile one of the notions that stuck with me was something similar to the Iron Triangle presented in this article (link). The idea was that the product owner and stakeholders would be presented with the project variables (scope, schedule, and resources). After flushing these out they would be asked to identify which of these variables is fixed, which is firm, and which is flexible. The caveat is that each of these can values can only be used once.

managing-project-variables

When marking the variable that is fixed the stakeholders are identifying the part of the product that cannot be changed in order to provide value. Maybe the scope (features) is fixed because the capabilities defined already were scaled back so that the minimum viable product (MVP) was being built.

The next variable is marked as firm. The variable identified in this manner is one that the stakeholders can give on here and there and still achieve value. For example if the scope was considered fixed, then the schedule that was proposed might be able to change depending on how the project moved forward.

The last variable is considered flexible. This is where the stakeholders have the most ability to change things so that the other two variables can be met. In this example, the resources (servers, teams, support, training) are where the stakeholders can invest the most to meet the scope and schedule.

This technique has proven helpful in shaping expectations on a project. Though it is important to continually evaluate these variables along the way. What really stuck with me was this. When the instructor explained this concept, he wisely noted that one variable was left off the chart. This was because is was non-negotiable. That was code quality.

 

Advertisements

Write Programs for People First, Computers Second

There are several computer books that have become classics. One of these is Code Complete by Steve McConnell. The first edition was written in 1993. That goes back to when I started collecting a paycheck as a professional developer. And it precedes classics like the Gang of Four’s Design Patterns (1994), The Pragmatic Programmer: From Journeyman to Master (1999), Agile Software Development: Principles, Patterns, and Practices (2002) and Clean Code (2008). Some consider this book to be the first collection of coding practices.

In this book, McConnell stresses the importance of readable code.

codecomplete_readable

He notes that writing readable code is one of the things that separates the great coders from the rest.

A great coder [level 4] who doesn’t emphasize readability is probably stuck at Level 3, but even that isn’t usually the case. In my experience, the main reason people write unreadable code is that their code is bad. They don’t say to themselves “My code is bad, so I’ll make it hard to read.” They just don’t understand their code well enough to made it readable, which puts them at Level 1 or Level 2.

Even before Code Complete, the book Structure and Interpretation of Computer Programs, written by Abelson and Sussman, was published in 1985. The full text of the book is available online (link). The preface to the first edition (link) contains the oft repeated line:

programs must be written for people to read, and only incidentally for machines to execute.

Why is readability so important?

As famed developer Joel Spolsky notes: It’s harder to read code than to write it.

We have all been there. We saw a problem, rolled up our sleeves, and wrote some code that we thought was quite clever. Maybe something like this (credit for this gem goes to this code golf puzzle).


"Gdkkn\x1fVnqkc".split("").collect(&:succ)*''

Or maybe this (modified from a DailyWTF sample)

var m = function(p1) {
	if (p1 > 0 || p1 < 0) {
 		return parseInt(("-" + p1).replace("--", ""));
	}
	else { return p1;} };

And we walked away feeling like this

solo_i-rock

Unfortunately, the rest of our team took one look at it and reacted more like this

solo_shooting-self

Why? Because the code is hard to read. And if it is hard to read it will be hard to understand. And if it is hard to understand it will be hard to maintain.

Bob Martin explains this more in Clean Code, noting that we spend more time reading code than writing it.

Indeed, the ratio of time spent reading vs. writing is well over 10:1. We are constantly reading old code as part of the effort to write new code.

… There is no escape from this logic. You cannot write code if you cannot read the surrounding code. The code you are trying to write today will be hard or easy to write depending on how hard or easy the surrounding code is to read. So if you want to go fast, if you want to get done quickly, if you want your code to be easy to write, make it easy to read.