“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”—Martin Fowler
Writing clean code is a common topic in software development. But what exactly does it mean and why do we care about it?
To answer these questions, we spoke with Ali Spittel, Senior Developer Advocate at AWS and former faculty member at General Assembly’s Software Engineering Immersive.
Table of Contents
1. Defining Clean Code.
First off, we need to understand what clean code is. In short, clean code is easy to understand and easy to change. “It’s code that another developer can read and understand and easily extend,” Ali explained. “It’s code that multiple people can work with and that follows a set number of guidelines that the team has agreed on.”
2. Why Writing Clean Code Matters.
A lot of developers might think, “My code is working well and my client is happy, so why should I care about writing clean code?”
Even if your code is working right now, you have to keep the future in mind. If the code isn’t clean to begin with, it’s going to be much more difficult to maintain, update, or extend it in the future.
3. How to Determine Code is Clean.
Ali asks herself these questions when evaluating whether or not her code is clean:
- Who else is going to see this code?
- How easy is it going to be to update this code when new features are needed or new merges of the software are rolled out?
- How easy is it going to be to maintain and extend this code?
4. Essential Tips for Writing Clean Code.
The idea of writing clean code is subjective. There are some best practices out there, but rarely will you find a guideline that developers can consistently agree on.
But with that said, we need somewhere to begin. We need some ideas and advice for how to go about writing code that’s clean.
Below are 7 tips that Ali applies to write clean code.
1. Use clear variable and function names. Code becomes much easier to read if you write out full, descriptive variable and function names.
2. Write short functions that only do one thing. Functions are more understandable, readable, and maintainable if they do one thing only. If there’s a bug when writing short functions, it is usually easier to find the source of that bug. Also, the code will be more reusable.
3. Write good documentation for your code so that future developers understand what your code is doing and why.
4. Be Consistent. When writing code, consistency is key. People shouldn’t be able to look at a code base and tell exactly who wrote each line of code without a git blame! If you are using semicolons in JavaScript, use them at the end of each statement. Use ” vs ‘ consistently as well!
To begin with, you can set up a style guide and a linter to enforce these standards. Having those set up saves time when you’re writing code and makes sure you have some standard and consistency across your code base. For example, Ali recommends Standard JS for JavaScript and PEP8 for Python. She’s also set up her text editor to enforce these standards when saving her work.
5. Encapsulation + Modularization. Group like variables and functions in order to make your code more reusable and understandable. Break long programs into different files so that your code is more modular and digestible. Long files are often hard to sift through, and you may want to use small chunks of code from project to project. Group like items in your code so that it is more reusable.
6. Sandi Metz’s Rules. Sandi Metz, Ruby developer, speaker, and author, has four rules for writing clean code in object oriented languages.
- Classes can be no longer than 100 lines of code
- Methods and functions can be no longer than 5 lines of code
- Pass no more than 4 parameters into a method
- Controllers can instantiate only one object
“At first it’s really challenging to follow these rules,” said Ali. “A lot of developers disagree with them and think they’re too restrictive.” But for Ali, adhering to these principles for several months allowed her to get in the right pattern of thinking. Now the concepts come naturally as she writes code.
To get more detail on Sandi Metz’s 4 principles, check out her full talk!
7. The DRY Principle: Don’t Repeat Yourself. This is one of the first things that developers are taught. “Early on, I think it’s a really great rule for why we’re writing code in the first place and how to think about code,” said Ali. “We’re writing for loops and functions so we don’t have to write the same piece of code over and over again.”
That being said, applying the DRY principle too much can lead to over abstraction. Ali explained that over abstraction can be especially common when developers get more advanced. “But early on, it’s helpful to think ‘Okay, am I doing similar code in 8 different places? If I am, I need to think about how to make this into a function.’”
Conclusion
Ali explained that she doesn’t use all of these principles all the time. But they can still be helpful guidelines to help write code that others can read and change down the road.
A key takeaway she recommended was to at least start by setting up an automatic linter or code formatter. She explained, “I think that’s the easiest win. That way, every time you save your code it’s done for you. You don’t even have to think about it.”
