What is Clean Code?
Overview
The definition of clean code can be very subjective on the margins. However, from an absolute perspective, there are telltale signs that can be observed to point to code smell. Most of this post examines the various forms of code smell as a way to guide the way towards clean code.
At its core, clean code is about readability, maintainability, and extendability. It’s code that can be easily read, understood, and modified. There’s an element of consideration and an effort to avoid obfuscation.
Learn more about obfuscation at What is Object-Oriented Programming?
Table of Contents
Common Pitfalls
Over-Engineering
Over-engineering is common among eager and excited engineers who have recently learned about new design patterns, programming paradigms, or language features. It’s easy to want to show off your skills by writing code that uses as many patterns and features as possible. However, this adds unnecessary complexity that makes code more difficult to read and maintain.
Brevity Over Readability
Another way to show off skills (especially in languages full of syntactic sugar, like Python) is by trying to pack as much logic as possible in as few lines as possible. It’s true that concise code is one way to define clean code, however, this practice makes code more tightly coupled, less readable, and much more difficult to maintain and extend.
Overly Eager Optimization
- Too much extendability or genericization: Extendability is a key aspect of clean code. However, it’s easy to take this too far and modularize components to make them capable of handling
Nconnections, when only one is foreseeable. - Over-performance: It’s easy to anticipate that a feature will need a certain level of performance that will never be required given its customer base.
- Over-extending security: It’s impossible for anything that is connected to the internet to be 100% secure. At the highest margins, each incremental percentage of additional security comes in at double the cost of the previous percent (very roughly speaking). The extent of security needs to be measured with the size of a project.
Dogmatic Adherence to Rules
Rules serve as important guiding markers. However, most rules have exceptions. Attempting to fit every solution into every possible rule could result in (at least) stifled innovation and decreased productivity.
Inconsistent Naming Conventions
Inconsistent naming conventions result in worse readability. Consistency is everything.
Refactoring Too Late
Software is malleable. Very often, one solution outgrows its use case as needs change over time. This over-extending of an existing solution can result in increased overhead for each change that uses this outdated solution.
Under-Documenting
The most important way to document is with good variable names. The second most important way to document is with code comments. The third most important way to document is through READMEs and Wikis. The third one is optional and depends on the complexity of the feature. Failing to document sufficiently results in difficult readability and understanding of the code’s behavior.
Conclusion
If you’re working in a team, it’s important to remember that writing code is for your teammates and those who work on the codebase when you’re gone. Every decision, even technical, needs to balanced against maintainability.
To be updated with examples, and diagrams that depict spectra and quadrants of tradeoffs.
Author
Sam Malayek works in Vancouver, using this space to fill in a few gaps. Opinions are his own.