A Few Principles of Clean Code

Bad code works until it's the year 2,000. Bad code is difficult to understand, more complex than it should be, not easy to test, and it makes other developers seethe with frustration. While it might take longer to write clean code in the short term, it's beyond established that writing clean code will save everyone time, effort, and ultimately money.

But there's always room to learn. No one writes clean code from the beginning. Recently, X-Teamers discussed their most important principles to keep their code clean, and we decided to share the best ones with the world.

Clean Code Principles

Clean code doesn't rely on language-specific rules. Instead, it relies on language-agnostic principles agreed upon by the developer community. As such, even though the initial question on our Slack channel was about how to keep your JavaScript / TypeScript code clean, X-Teamers replied with some of the general design principles of clean code.

KISS: Keep It Simple Stupid. A design principle originating from the U.S. Navy that goes back to 1960 already. It states that most systems should be kept as simple as possible (but not simpler, as Einstein would have said). Unnecessary complexity should be avoided. The question to ask when you're writing code is "can this be written in a simpler way?"

DRY: Don't Repeat Yourself. Closely related to KISS and the minimalist design philosophy. It states that every piece of knowledge (code, in this case) must have a single, unambiguous, authoritative representation within a system (codebase). Violations of DRY are referred to as WET: We Enjoy Typing, Write Everything Twice, Waste Everyone's Time.

YAGNI: You Aren't Gonna Need It. A developer should not add functionality unless deemed necessary. YAGNI is part of the Extreme Programming (XP) methodology, which wants to improve software quality and increase responsiveness to customer requirements. YAGNI should be used in conjunction with continuous refactoring, unit testing, and integration.

Composition over inheritance: Not an acronym, sadly. It's a principle where you design your types over what they do instead of over what they are. It's explained in more detail in this video. One of the ways to implement this principle is with the Object.assign() method in ES6.

Composition is favored over inheritance by many developers, because inheritance forces you to build a taxonomy of objects early on in a project, making your code inflexible for changes later on.

Favor readability: It's not because a machine can read your code that another human can. Particularly when working with multiple people on a project, always favor readability over conciseness. There's no point in having concise code if people don't understand it.

There are many ways to make your code more readable. Two examples are placing common numbers into well-named constants (e.g. const CACHE_TIME = 200;) and creating long names instead of shorter ones (e.g. userHasFormAccess over canAccess, which doesn't tell as much).

Practice consistency: This is arguably the overarching principle of all clean code principles. If you decide to do something a certain way, stick to it throughout the entire project. If you have no choice but to move away from your original choice, explain why in the comments.

Of course, this is by no means a comprehensive list. There's so much more to clean code. In fact, if you want an excellent book on clean code, we recommend The Art of Readable Code by D. Boswell and T. Foucher.

Want more? Read about programming best practices to improve the way you write code.