Clean Code means Coding Without the Bullshit
TLDR: Writing Clean Code Without the Bullshit means treating our code reviewer’s time as more important than our own. To write clean code, update your definition of “done” to include refactoring.
Why should you care about writing Clean Code?
As engineers, we often spend more time reading and modifying existing code than we do writing new lines of code. If your code is clean, it is easier to read and therefore easier to maintain. This leads to fewer bugs, fewer Slack messages asking other engineers for clarification, and an easier time reviewing PRs.
What is Clean Code Without the Bullshit?
Robert Martin, aka Uncle Bob, wrote the book Clean Code giving us engineers a guide for writing code that was easily readable by others and easy to maintain. The book Writing Without the Bullshit, which I’ve summarized here, provides rules for keeping your business writing clean and elegant. The core rule in Writing Without the BS is to “treat the reader’s time as more important than your own.”
We can take this rule and apply it to code. All of the rules Uncle Bob lays out for us can come from the one rule of “treat the code reader’s time as more important than your own.” If we engineers can adopt this single rule, it will motivate us to spend the extra time necessary to refactor our code after we get it working.
How do we write Clean Code Without the Bullshit?
Adopt the Golden Rule
Above all else, remember to treat the code reader’s time as more important than your own. This means you’ll spend the extra time to think about what you just wrote and how you can make it better, cleaner, and more readable for someone who doesn’t have the full context. This rule will motivate you to go back and refactor after you’ve gotten your code working.
Change your Definition of Done
When we get our code working, we often stop there, make our PR, and close the ticket. Uncle Bob is quick to point out that when your code is working you are actually only halfway done. At this point, you should spend the time to refactor, document, and clean up your work. Make it easy for someone who doesn’t have the context to see what is going on here.
Talk to your team and build the culture around the new definition of done is the code works and we’ve refactored it so it’s clean, extensible, and easy to understand. Once you get your code working – now you need to go back and refactor it.
Follow these Clean Code guidelines
These are a few rules I’ve copied from Uncle Bob. For more details see his YouTube Series or the original book Clean Code.
Functions
- Functions should do one thing. Keep extracting methods from your function until you can’t anymore. Many IDE’s have a built-in refactor feature to make this part easy.
- Name your functions using verbs. Since they should only do one thing, call your function by the verb that it is doing.
- Functions should be short. Uncle Bob says shorter is better, the first rule of functions is they should be small, and the second rule is they should be smaller. Aim for 3-5 lines long and only 2 levels of indentation.
- Use fewer arguments. Limit to 2-3 arguments per function, the fewer you pass the less context the reader needs to keep in mind while reading your function.
- Do not pass booleans to your functions. Instead, you should have two different functions that you call instead.
- Be polite and allow your readers to escape early. Not every code reader needs the same level of detail. The function name acts as a headline. Inside that function, there should be other function calls at the same level of abstraction. Each function call would go a level deeper into the details. This allows your reader to not get the details unless they want to.
Variables
- Name them well. Make it clear what this variable is, be more verbose.
- Use searchable names. Do not use any magic values (ie. DAYS_IN_A_WEEK = 7 instead of just x = 7).
- Keep the naming schema consistent. Don’t switch the terms for certain concepts. For example, don’t use “csv_decoder”, “json_parser”, “html_reader”` if they all do the same thing for different file formats.
- Create explanatory variables. If you have a small formula that requires a few variables, rather than inserting the formula somewhere, just make the extra variable to enhance readability. For example instead of :
my_function(x * y)Use:
area_of_square = x * y
my_function(area_of_square)What’s Next?
Actions
- Remember the “golden” rule – treat your code reader’s time as more important than your own. Once you get something working, don’t stop working on it, go back and refactor.
- Talk to your team about redefining “done” when you work on a ticket. Have that definition done include time to refactor and make your code more readable.