I recently had to do work on a project that numerous other developers worked on over a span of two years. The biggest challenge I faced was striking the right balance between "refactoring" the old bad code, while still delivering new features. In this post I want to highlight some of the common mistakes that could have easily been avoided by applying basic clean coding principles.
Working on a codebase such as that one reminded me dearly of when I first started working as a developer and my mentor recommended the book "Clean Code, by Robert C. Martin" to me. I enjoyed it and read it on my commute to work every day until I was through it. Most of the concepts stuck with me and I still apply them every day. I fondly remember how one of my non-developer colleagues used to laugh at me because of how passionate I was about the book.
This post is not meant to be exhaustive or ridiculing the developers of the codebase, it is just meant to serve as a good reminder of things to watch out for.
Pitfall 1: Nested asynchronous functions with callbacks.
The codebase was filled with callbacks upon callbacks. I can forgive that the code was written before async/await was mainstream, but Promises should have been used to keep the code easier to read, troubleshoot and maintain. Instead of using callbacks, use async await.
Pitfall 2: Duplicated code, lots of it.
It just speaks for itself - the codebase was much larger than it needed to be because of a lot of code duplication. The project was JavaScript-based and relied on Asynchronous module definition (AMD), but they completely failed to capitalise on one of the built-in promises of AMD, i.e. "to encapsulate code in smaller, more logically-organized files". I think a good approach to avoid code duplication is to use JavaScript Classes and TypeScript interfaces (if that level of abstraction is beneficial), but even just "utility functions" are better than duplicating code.
Pitfall 3: Cute/sarcastic comments, commenting out code instead of deleting.
The code had many comments in which the developers might have thought were cute or funny at the time, but when I had to debug and decipher what the program was supposed to be doing, it was not cute or funny any more. Another major downside of the code was a lot of code that was commented out instead of just deleted. Version control systems are amazing at "remembering" important code, and it is very easy to get old code back.
Pitfall 4: Not using explicit yet concise function and variable names
This one also speaks for itself. One should try and use variable names and "code dialect" that is commonly used for what you are trying to achieve. For example, when functions respond to user events, it is good to prefix it with something like "onClick" or "onSubmit", instead of something like "clickedButton".
Pitfall 5: Not ensuring type safety.
There is a definitive overhead when you first start using TypeScript, and you have to write more code and think more about your models than you would if you don't use it. But the benefits of using it are enormous. This code base had no sense of type safety, and it really showed in the code and led to many issues in production which could have been avoided.