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?

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 N connections, 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.