The Beginner’s Guide to Clean Code
As a beginner in the vast and complex world of software engineering, I began with two dangerous misconceptions:
- The first was that coding was just a big game of Pokemon. My only job was “catching” or in this case learning all the languages and then using them to write some code.
- The second, was that the only one who had to read my code was the computer. Well duh! Who else, right?
Imagine my surprise when I learned that there was such a thing as “good code” and that this was what I would be expected to write. Not only that, but my code had to be “readable”, so that co-workers and future collaborators could understand it!
I wish I could say that from that moment forward I dedicated myself to learning the principles of writing clean and readable code. Alas, that was not my approach! Instead I moved on to another terrible and perhaps even more dangerous misconception:
That because I was a beginner I somehow got a free pass on this “clean code” concept.
I was quickly disabused of that idea. I wasn’t paying attention to how I named things, so when I came back to my code, I spent ages trying to decipher it.
I iterated through things with no clear concept of what they were, what I was expecting in return or how to work through the errors.
My code had bugs on bugs on bugs and my methods were longer than Les Miserables(a book so long that it’s famously known as “The Brick“).
If that wasn’t bad enough, I then found the Holy Grail: comments!
“My code makes no sense.” I thought “But I can explain what I mean in the comments!”
I was forming terrible habits and was building my knowledge on a foundation made of Jenga blocks. I eventually realized how deeply this was hindering my learning and began taking steps to rectify it.
There are several things to know before making the commitment to a clean code lifestyle. The first being why.
Why should you write clean code?
1. It actually saves you time
You could spend hours looking through a project trying to figure out what a method you wrote 2 weeks ago is supposed to do, or 20 minutes throughout making your code easy to read.
2. Debugging will be easier
Clean code will help you debug faster. It also allows your colleagues to easily jump in and help you, if needed.
3. It makes collaboration smoother
Another misconception of programming is that you’ll be working alone but in reality that’s just not true. More often than not you’ll be working with other people. Make this collaboration as effortless as possible by writing beautiful, clean code that they can easily work with.
“Remember! You are responsible for the quality of your code!”
While doing research on how to clean up my code I ran into this idea several times and it really changed my mindset on the topic. Taking personal responsibility for my code meant that I was creating something that was important to me, and I was creating it with care and consideration.
Ok now you’re sold! You want to write clean code, but…
What does clean code even look like?
1. Elegant
Whoever reads your code should be able to know what it does. It should make sense to them.
In the words of Grady Booch “Clean code is simple and direct. Clean code reads like well-written prose.”
2. Focused
Code should be simple and stream-lined. It should follow the Single Responsibility Principle (more on that below).
3. Easy to maintain and change
Adding features to your code or changing existing features should be seamless.
Now that you know the why and the what, I’m going to show you the how!
There are a great many books, articles, and videos out there for writing clean code but I’m going to focus this list on beginners, such as myself.
How can we start implementing clean code into our programs?
1. Plan!
Don’t start writing code until you’ve drawn out your models and you’ve delineated what you want to do. If you know exactly what you want it’s easier to write it cleanly!
2. Indentation
This one might seem simple but what a difference it makes! It’s easy to overlook proper indentation when you’re a beginner but if you take those few extra seconds to indent, the readability of your code goes from zero to hero.
3. Naming with intention
Ideally the names you give your variables, methods and classes should reveal why it’s there and what it does. These names should also be easily pronounceable. One common practice to keep in mind is using nouns for class names and verbs for methods.
4. Single Responsibility Principle
Make sure your classes have responsibility over a single part of the code’s functionality.
5. Separation of Concerns
Each responsibility/concern in your program should be separated into its own section.
6. Simplify your methods
Generally your methods shouldn’t be longer than 5 lines and should have no more than 3 arguments. If your method is getting too long, it can probably be split into 2 (or more) methods. If you have too many arguments, maybe some of those should be wrapped into their own class.
7. DRY
Don’t Repeat Yourself! Always check to see if you’ve already built something similar. If you’re repeating a line of code over and over again, it might be time to refactor.
8. Don’t use comments as a crutch
If you find that you’re using comments to explain or even justify your code, take that as a clue that you need to clean that code up.
9. Don’t hardcode
Part of writing clean code, is writing code that can be easily changed or updated. Hardcoding is an update’s arch nemesis. Your code is Gotham and hardcoding is the Joker. The good news is that this makes you Batman!
10. Test!
Make sure you’re constantly testing! Dealing with bugs immediately saves you time in the long run. This prevents your code from becoming messy and disorganized while you’re debugging.
Writing clean code can seem like a daunting and tedious task at first but it’s one of the benchmarks of an effective programmer. You’ll be saving time and optimizing your learning. It does take more effort to write clean code but it’s a habit like any other that can be built up and improved over time. It also can be taken step by step. Start by indenting with care and before you know it you’ll be building programs that are elegant, readable and flexible!
“An ounce of prevention is worth a pound of cure.” Benjamin Franklin