What does it mean to write Clean Code

The short answer is "Code that follows the practices and principles in the Clean Code book by Uncle Bob"

But let me elaborate a bit. Some years ago I discovered some articles by Robert (Bob) Martin aka. Uncle Bob, which I found interesting and well written, not least because Bob is a bit of comedian and is brilliant at making dull subjects interesting through humour. In one of the articles I found a link to a book he had finished recently and followed the link to buy the book from Amazon (later I went back to buy the Kindle version for my iPad).

This book had a huge impact on me and I changed my coding style in pretty much every language to follow the principles and practices presented by Uncle Bob. Later when Uncle Bob released The Clean Coder I immediately snapped up a copy and again it had a big impact changing my attitude towards what it meant to be a professional code craftsman. Since then whenever I have been a leader or influencer in a team I have pushed these books to my colleagues, even buying copies for some of them.

It is impossible to condense a complete book into a single blog post, but I do want to highlight the key take away for me that I have applied and evangalised over the years.

Whether it is test code or production code each code file should tell a story. Some people use the term "self documenting" but that doesn't quite capture the sentiment. I do tend to preach about TDD to the point that I am often heard to say "The tests are the documentation, the code is the design". This doesn't always go down so well, and the powers that be insist on "proper" documentation but I still write my code according to this principle.

So what does it mean for code to tell a story?

Lets think about tests first. I always practice Test Driven Development (TDD) and except in rare cases each test makes a single assertion. I also strictly follow the rule that "no production code should exist without a test", so I always write the tests first and follow another rule "always assume the type or method exists" using Resharper or VS Code extensions to actually create them. The result being that my tests tell the story of the unit under test because they are written in a sequence that both describes and builds the unit under test according to the flow of the code. I often see people using auto formatting features of tools to organise production code but not so much for test code. I am a big fan of snippets or Live Templates as Resharper calls them and use them extensively to speed up my coding and apply consistent organistion of code files. For example I have multiple formatting rules setup for Resharper depending on the file type including rules that format test files for NUnit and xUnit. These rules help my test files tell a story by placing any SetUp method or constructor first then all of the test methods next. All fields, properties and helper methods are placed after tests and ordered accodring to type, access and name. The result is that when I open a test file later I can read the story of the unit under test through the friendly descriptive names of test methods and their sequence.

What about production code. As a developer who prefers strongly typed languages (C, Java, C#, TypeScript) it is rare for code to exist outside of a class and since I apply SOLID principles to all of my code, production code files tend to be concise and focused on one thing. To tell a story production code must use friendly descriptive names for everything, long names are not uncommon and often necessary to be descriptive. Methods are small and do one thing and one thing only, for example a method that includes conditional logic (if or switch) making decisions is the only thing it does, each conditional block calls another descriptively named method. Methods are organised according to their usage. The constructor is always at the start of the file (preceded only by private fields if any) and any destructor is always last. If I have a method named something like Initialise or Start then it would be placed immediately after the constructor. Any methods that are used by a public method follow it and are organised in the order they are used so as you look at a public method the story of what it does is apparent from the methods it calls, which follow immediately after should you need to drill down.

A key component of telling a story in code is naming conventions. I know some developers like to keep names short to save typing, but this practice detracts from the story and IMHO doesn't really save any time or effort in the long run, short non-descriptive names are a false economy. Names of everything are important, even private and local elements, they should describe what the element does or stores, without the clutter of greek notation or similar conventions.

Another key component is keeping methods small and focused on doing one thing. As soon as you find yourself writing more than two or three lines in a block consider putting it in a private method that describes what it does. This approach really enforces the "telling a story" concept as it is easy to read what the class or component does from the method names.

One area of the Clean Code book that I disagree with to some extent is comments. Uncle Bob advocates that comments are completely unneccessary if descriptive names are used and methods are focused on doing one thing. By and large I agree, comments are a waste of space, except in one case. Sometimes you need to explain why you wrote some code the way it was written. As we all know there is frequently more than one way to acheive something and when you make a choice to go one way rather than another then I believe there is value in adding a comment that explains the choice. I'm not advocating this for every choice, but when you are writing a block of code where the reasoning is not obvious a comment can go a long way to making it easier to understand when you or a colleague come back to the code later. As a long time contractor I have often found myself grateful for such comments when picking up code written by someone else.

If you haven't read Clean Code I strongly urge you to do so, it is not a new book but it's content is as valid today as when it was first published and it will definitely make you a better programmer.