I like clean code
But what does it mean?
When I introduce myself to a new team or client some of the things I say include my educational background, how many years I’ve been an iOS developer, and what my biggest or most known projects were. I also say that I like clean code. But what does that actually mean? And does it mean the same thing for every developer? How do you know if your code is “clean”?
Clean code is a code that is written by someone who cares.
Michael Feathers
For me, clean code is code that is written in a way that other developers will easily understand. Well, maybe that also depends on the actual feature, but clean code makes it easier for you to focus on the actual logic of the code without being bothered to search for the essence through the mess.
Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. … [Therefore,] making it easy to read makes it easier to write.
Robert C. Martin
The truth is, like Uncle Bob said, we spend a lot of time reading code, not only writing. We don’t write code for machines. If it was true, we would still write in assembler, or even better — in 0s and 1s. After all, this is what our computer understands. We write code for the “future us” as well as other developers. And this is the most important thing when trying to understand what clean code is.
So after this really long beginning, let’s get into more detail. I will give you some advice and what helps me to write clean code. As an iOS developer, I will mostly discuss Swift language. Some, if not most, of my advice can easily be transferred to other languages.
Make sure you know some “standards” of your language
Even though clean code is a subjective matter, make sure that you know some of the standards other developers use. For Swift language, there are some guidelines from known sites. There are also some big companies that you can find and get to know and try to incorporate into your coding. Some examples include:
- https://swift.org/documentation/api-design-guidelines
- https://github.com/raywenderlich/swift-style-guide
- https://github.com/linkedin/swift-style-guide
- https://google.github.io/swift
Make code review on a daily basis
I think writing clean code is like cybersecurity — it’s a journey, not the destination. I still learn and I still make mistakes. That’s why there’s another thing I love as much as clean code — code reviews!
Doing code review helps us in so many ways I don’t even know where to begin. We learn every day because others can find our mistakes and suggest ways to improve. We can also check someone else’s code. Helping others correct their mistakes trains us not to make the same mistakes in our code.
Code review helps us quickly check what is most important in clean coding — whether the code in our project is easily readable by other developers. It also helps us maintain the same coding style throughout the project, which is actually another piece of advice:
Keep code in your project consistent
This is probably the most important thing in keeping your code clean. Different developers can have different opinions on what looks good in the code. In most cases, it’s ok if you’re consistent in the whole project (and using a coding style more or less common in your language :)).
The ideal situation in any project is to write code in a way that no one could say was written by different developers. I know that this is really hard and sometimes even impossible, but we should try doing this to maintain the same style. This is especially important when you start working with developers you don’t know. You can have different habits but you should establish a set of rules that you will all apply in the project. A consistently written project is much easier to read later on.
I usually prefer democratic voting to establish some ground rules.
And what rules can these be?
How you make indentations in the project
And that’s ok. As long as you set the same rules for the whole project. For example, we do an indentation like in the former example as long as there is a minimum of 2 parameters in the function. If there is only 1 — we use the latter example.
Do you do one-liners?
How do you handle newlines in reactive programming?
I personally like it when each new line with action in a reactive chain begins with a dot. But this is just my preference, you can create your own rules.
e.g. in Combine:
or in RxSwift:
How do you name your classes and protocols?
- For logic singletons — do you use Managers or Services?
- Do your protocols have a Protocol suffix or not (e.g. ViewModelProtocol)?
- Do your table cell classes have a suffix Cell or TableViewCell?
And there are many many others…
…that will probably come up during code review. The best time to start establishing new rules is after seeing differences in our code.
It’s always a good idea to write these down in your README file, so everyone in the project (now and in the future) knows what the rules are.
Help yourself with some tools
Of course one of the best things for us to use to help us keep code clean are linters.
SwiftLint
SwiftLint has become a standard in the iOS community. If you don’t know it yet — I highly encourage you to check it out. It is a tool to enforce Swift's style and conventions.
Using SwiftLint is the best way to remain consistent in coding style in the project. You can set how many lines of code a function should have; how many of them should have a file; that you can’t do force unwrappings; how many characters a line should have, and many more. It is customizable, so you can change some settings according to your preferences. It will show you warnings and errors in code when you fail to follow the set of rules.
Don’t be scared when you add SwiftLint to your existing project — it won’t compile and show you hundreds of warnings and errors. The beginnings are hard, so it’s best to use SwiftLint from the beginning of your project.
However, if you want to add it to an existing project I have one piece of advice for you — do it gradually. You can disable all rules in swiftlint.yml — a configuration file. And, for example, each week, enable one of them, until you reach its full potential.
Also, please use SwiftLint wisely. You can always use swiftlint:disable in your code to disable a warning, but it is there for a reason. Think twice before disabling screaming SwiftLint. Maybe your method doesn’t have to be so long and you can make two out of them? Or you can add a guard instead of doing force unwrapping?
Danger
Another useful (but not so popular) tool is Danger. Danger runs during your CI process and gives you the chance to automate common code review chores. It’s totally customizable. In fact, it’s up to you to write code that will be applied to your CI during code review. Why during code review? Because Danger will be your code review buddy :). It will post comments to your pull request.
Most of the examples shown on the Danger website and on the internet contain:
- SwiftLint warnings and errors as comments in your PR — no more forgetting to check the warnings list in Xcode before pushing a pull request. Danger will do that for you.
- Warnings about changing some crucial files in your project — make sure that changes in some important logic don’t go unnoticed during code review.
- Ensure smaller PRs — show warnings or even errors on a pull request that it is too big and the author should make a few smaller PRs, among many other examples.
Don’t forget to keep your repository clean as well
I know this is a blog post about clean code, but let’s not forget that our code, in most cases, lives in a repository. And this repository can also be clean or messy.
On a day-to-day basis, you make pull/merge requests, change branches, and sometimes even search through git commits to find a place where you or your coworker added that nasty bug. All of that is easier when you:
Have consistent branch naming conventions
If you use gitflow you can decide that your branches will look like this. Some of the examples you can see below. The key is to be consistent and use one of them.
Decide whether you should squash pull requests or not
I know this is like a discussion between using tabs and spaces and there are some good points for and against squashing. I prefer to avoid squashing in favor of writing meaningful commits that could potentially help me during debugging and searching for some old changes.
Keep your git commits readable
I like to apply rules written in this article to git commits. In short, keep them simple, imperative, always start with a capital letter and an action, and don’t end with a comma.
Any fool can write code that a computer can understand.
Good programmers write code that humans can understand.
Martin Fowler
And that’s it! I hope you enjoyed this blog post. I think it will be helpful in your journey to maintain clean code in your projects.
