At the inaugural WordCamp US, Michael Toppa, CTO at Poka Yoke Design, shared 10 tips for writing clean code. These tips and techniques are applicable across languages. They're straight to the point. They are understandable and sensible, just like your code should be.
Why is clean code important? Clean code saves time. Clean code makes maintenance easier. Clean code makes things better for other developers who work with your code in the future.
When it comes to writing code, an ounce of prevention is worth a pound of cure.
Writing in Clean Code: A Handbook of Agile Software Craftsmanship, Robert C. Martin notes that the ratio of reading code to writing code is 10:1. In other words, the actual time spent typing is significantly less than the time spent reading, even in development. Clean code makes better use of that reading time.
"We spend most of our time staring into the abyss rather than power typing." ~ Douglas Crockford
So how do you write clean code? What do you actually do? According to Toppa, there are 10 things you can start to do today. Here they are.
1. You are responsible for the quality of your code.
You are responsible. Not your client. Not your boss. You don't tell your doctor to skip washing their hands because it saves time. Standards and quality are important.
2. Use meaningful names.
Variables shouldn't be cryptic. Use
$elapsed_time_in_daysor
$days_since_creationinstead of instead of
$dIf you do this, later in your editing session, and next week, next week and next year, you'll know exactly what that variable is referring to.
3. Write code that expresses intent.
Things in your code should explain what they do in their names. For example, name methods in such a way that the method name explains what it does. Clean code reads like well-written prose.
4. Comments are often lies waiting to happen.
While comments are important, code should speak for itself whenever possible. When commenting extensively, you now need to maintain the comments, as well as the code. So what? The reason this matters is that incorrect comments might take a future developer down the wrong path. Please note this does *not* say "never write comments." Instead, expressive code requires less commenting and is cleaner.
5. Leave your code better than you found it.
Not only should you write clean code, but also take a few minutes to clean up cruft when you find it. Following this mantra means that code can actually get cleaner and cleaner over time.
6. Follow the single responsibility principle.
A clean piece of code does one thing, it does it well and it does it only. Just because you can, doesn't mean you should. Look for cohesiveness. If you are trying to do too many things in one class, it's a problem.
7. Write tests.
Toppa is a fan of two kinds of tests: unit tests and integration tests. Unit tests test functionality in isolation. Integration tests ensure that a change over _here_ doesn't break something over _there_. Test-driven development is an approach that helps ensure that tests are in place and can help keep code clean.
8. Use agile workflows.
Don't work in monolithic, six-month increments. Instead, work on small, independent portions of functionality, and ship and test often. More importantly, be committed to a culture of ongoing, iterative customer feedback.
9. Have independent architecture.
There are good practices that can be applied across different frameworks. Don't be dogmatic about architectures and approaches. A core good idea can be applied in different situations, when appropriate.
10. Practice, practice, practice.
Musicians don't only play in front of an audience. Learn new techniques. Go to contributor days. Keep honing your craft.
These tips for writing clean code are a great place to start, and there are many resources available to keep tuning your coding chops. Have a tip or a resource? Share it in the comments.
