This is my first SWE-related blog post and it’s just a quick synopsis of a really great book I read a few years back - “Clean Code”, by Robert Martin. Meant to be more of a TLDR rather than an educational piece as most of it is still pretty fresh in my mind, and there’s diminishing returns and opportunity cost of time spent on this. I also haven’t read all of the chapters in-depth - some of them are really nitty or irrelevant.
Chapter 1 - Intro
This chapter is just an introduction/teaser. It talks about how clean code matters - maybe not in the short-term, but definitely over the long-term. Bad code compounds over time so that it becomes more and more difficult to make changes. Reminds me of how some people in crypto talk about how the US government is a system that becomes more and more inefficient over time, because new laws and regulations are always added but seldom removed. The result in both cases is compounding inefficiency.
Chapter 2 - Use Good Names!
Super important and one of the easiest ways to make your code more readable. Good names communicate intent, are specific and not vague, and add context. With good names, you can read code almost like reading normal writing.
Chapter 3 - Functions
Functions should:
- have good names
- be short, do one specific thing, and exist at one level of abstraction. You can hide multiple levels of abstraction by refactoring code into more functions.
- NOT have hidden side effects or dependencies
Chapter 4 - Comments
Boilerplate comments are bad. Comments should only be used when they can add meaningful information outside of what the code already provides. For example, an important design decision or some relevant detail that can’t be gleaned by just reading the code.
Chapter 5 - Formatting
Formatting matters! Makes the code more readable. There are surprisingly many kinds of formatting, including:
- splitting code into “paragraphs”
- having minimal vertical distance between first function calls and implementations, or variable instantiations and their usage
- ordering of different kinds of code such as fields vs functions
Chapter 6 - Objects and Data Structures
Abstraction abstraction abstraction. Display the interface and hide the implementation. Need I say more?
Chapter 9 - Unit Tests
Tests are important. In the short-term, tests might be the only informational signal you have as to what your code actually does. Either it passes the tests or it doesn’t.
The whole meme with TDD is to write tests before you write your code. From my own personal experience I’ve done this and think it’s a good way to go about things. Forces me to plan more before I write my code, and also helps me find and fix bugs as I write it.
Chapter 10 - Classes
More beautiful advice in here about how classes should be small, and have a single specific responsibility, just like functions!
Chapter 17 - Smells and Heuristics
A long laundry list of miscellaneous heuristics for judging/improving code quality. Good read… I recommend going through all of them.
My own closing thoughts
I found that once I understood better what clean code is (and what it’s not) I actually found it way easier to write clean code than bad code. I think this is because ultimately coding is an expression of logic, abstraction, and data flows and clean code is more discrete, abstracted, and composable than spaghetti code.
I think writing (good) code is more about reading code than writing code. I can draw lots of metaphors here:
- You learn how to become a good writer by reading, not by writing
- You learn how to speak Spanish by listening, not by speaking
In general, I think you can only enrich your informational output by taking in more information as input.
That’s all for this synopsis. Have fun writing clean code folks!