Some guidelines and resources on writing clean and readable code

September 01 · 6 mins read

A few weeks ago on youtube, I found a very interesting comment on coding principles by someone named veganaiZe. I’m going to paste the entire comment here so that it will not be lost in the comments section of youtube.

…I think the most important principles are the following:

D.R.Y. - Don’t Repeat Yourself - Pretty much self-explanatory. If you are re-writing the same block(s) of code in various places then you are ensuring that you’ll have multiple places to change it later. This is probably the #1 warning flag that you should look into an alternative/pattern.

Y.A.G.N.I - You Ain’t Gonna Need It - Don’t code out every little detail that you can possibly think of because, in reality, you probably won’t end up needing much of it. So just implement what is absolutely necessary (save the GUI until later, for example!)

K.I.S.S. - Keep It Stupid Simple - When in doubt, make it easy to understand. Don’t try to build in too much complexity. If a particular design pattern overly complicates things (vs. an alternative or none at all) then don’t implement it. This applies heavily to user interface design and APIs (application programming interfaces).

P.O.L.A. - Principle Of Least Astonishment - This has overlap with KISS… Do the least astonishing thing. In other words: DON’T BE CLEVER. It’s nice that you can squeeze a ton of detail into a single line of code. But your future self and other developers will judge it by the number of “F”-words per minute when they open your source file. It should be relatively easy to jump into what your code is doing, even for an outsider who isn’t quite as clever as you are.

Last, and most certainly NOT least…

S.O.L.I.D. (I saved this for last because it’s more specific, but it should probably land around #2 on this list)

Single Responsibility - A class should have only one reason to change; Do one thing and do it well.

Open/Closed Principle - A class should be open for “extension” but closed for “modification”.

L. Substitution Principle - Derived (sub) classes should fit anywhere that their base (super) class does.

Interface Segregation - Multiple specific interfaces are better than one general-purpose interface.

Dependency Inversion - Depend on abstractions NOT on concrete implementations. (Depend on abstract classes and interfaces, which can’t be instantiated, rather then any specific instance)

I would like to add the Uncle Bob updated the definition for the SRP to make it clearer:

A module should be responsible for one, and only one actor

You can read about that here and here and here and here

Other resources on how to write clean code

“Clean Code: A Handbook of Agile Software Craftsmanship” book by Uncle Bob Martin

Clean code always looks like it was written by someone who cares.

— Micheal Feathers

“The Most Important Design Guideline” by Scott Meyers

Make interfaces easy to use correctly and hard to use incorrectly.

“The Art of Clean Code” by Victor Rentea

The true cost (80%) of software lies in its maintenance, not in its initial development. (time 03:17)

“Name by role” by Mark Seemann

“The key to clean code”

“SOLID: the next step is Functional” by Mark Seemann

“Referential transparency fits in your head” by Mark Seemann

“Readability verification” by Mark Seemann

In Code That Fits in Your Head, I suggest heuristics for writing readable code, but ultimately, the only reliable test of readability that I can think of is simple:

Ask someone else to read the code.

Robert C. Martin’s book “Clean Code” adapted with JavaScript examples