7 Practical Tips for Writing Clean Code
“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.
Ali provided 7 guidelines that she uses to successfully ship clean code.
What is 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.”
Why do we care about writing clean code?
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.
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?
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.
- Use clear variable and function names. Code becomes much easier to read if you write out full, descriptive variable and function names.
- 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.
- Write good documentation for your code so that future developers understand what your code is doing and why.
- 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.
- 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!
- 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.’”
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.”