You are a developer. You read books, blog posts, and Tweets about the practice of how to construct clean code. Do you truly understand why? I never advocate blindly following. Rather, I encourage you to ask: Why should I care about writing clean, readable code? Let’s answer that question to provide clarity of the purpose and intent behind the practice. Let’s answer why.
When I ask the question of why to developers, I get a wide range of answers that boil down to these:
- It’s a best practice.
- It’s expected.
- It makes code more maintainable.
And when I probe deeper to ask why it’s a best practice, why it’s expected, and why it makes code more maintainable, at the root, developers aren’t sure why.
Clean coding is a popular practice being shouted and shared from our peers who have years and years of experience. It’s presented in such a way as “you have to” or else bad things happen. Why?
I want you to pause for a moment and think about these questions. See if you can formulate a reason why you’d invest your valuable time into making your code clean and readable.
- Why is clean coding a best practice?
- Why is it expected on your team, project, or company?
- Why does it make code more maintainable?
- Why should you care?
- Why should or shouldn’t you jump on board?
What do you think the root reasons are for all the buzz, books, and conferences? Why?
Yes, it is a best practice. We write procedures about what and how for achieving our best practices. But these are authoritative declarations of “do this in this way” via “these methods.” They are not the why.
Yes, it is often expected, to the degree that you will be measured by you compliance to these best practices. If you don’t, then you risk your code not being merged or you not being promoted or hired. But this “expectation” is part of the blindly follow model or else. It is not the why.
Yes, it does make code more maintainable and as a result, it will lower costs over the software lifecycle. But these are the benefits. You can think of them as the outcomes that result from the practice. They are not the why.
What is the Why?
The why is that you care. That’s the why.
By designing readable code:
- You care about the future you
- You care about your teammates
- You care about your community
Readable code means it’s readable by humans, i.e. anyone of any skill level can read it and follow along with what’s happening. It’s readable. It’s understandable. And when it get right, the code tells us what’s going on, why it’s happening, and how to use it.
By writing code in this way, by using clear symbol naming conventions, by breaking up code, by organizing like functionality together around a single purpose or intent, by building it smaller, by making it simpler, you are caring about anyone else who will need to fix it, add a new feature, strip it out, decouple it, or do a code review.
The why behind writing highly readable code — code that is expressive and tells anyone what’s going on and why — is that you care about others will come along after you write it. You are making that person’s job easier.
You care about people.
Code is for Us Humans
Higher-level programming and interpreted languages were built to make it easier on us humans to understand. These languages abstract away from 1s and 0s of machine language.
Why? It’s exponentially harder to write, test, and maintain code in assembly or machine language. We needed a human (not machine) way to express solutions in terms that we humans understand. How? Those before us built an environment that can emulate the way we naturally communicate with one another.
I emphasize “can emulate” because though it gives us that power, we have to choose to write code that way. Code is for us humans.
Our programming languages give us the means to name and organize stuff. By leveraging that central reason of “to make it easier for us humans to understand,” we yield tremendous power:
- We can write hard to read or follow code using obscure or unclear conventions that requires the manual, documentation, or some flowchart somewhere to work with it.
- Or we can infuse our common ways of communicating to ensure the message and intent are shining through and that everyone understands what we are doing and why.
Code is for us humans. We need to read it and know what is going on and why. We need to be able to work with it in order to do our work. The more clear, readable, and clean it is, then the more we understand, less time it takes us, and the less frustrations we incur in doing our work.
Being a Good Steward
The practice of clean coding centers on a human value of being a good steward for any other human who will look at or work with the code you build.
Why you should care about writing clean, readable code is this: you care about the people (your teammates, peers, community, and the future you). You care so much that you take the time now and in each line you write to ensure it is readable and understandable for another person.
The why is you care about the people who will look at or work with your code.
Great post, Tonya! Thank you for writing and publishing this. Many software developers support the practice of writing quality code (whether the goal is achieved or not). But I can’t recall anyone explicitly advocating directly for _why_ to do this. This post should be required reading for developers at all skill levels, from newbies to seasoned pros.
Good post. I like to comment my code in detail and use understandable names for variables and functions. If someone asked, “Why should I care?”, I’d answer: “So you can understand your own code after 2 years.”