#engineering #code #software #implementation

idea

The goal of producing clean code is to keep things simple, producing timely and adaptable code, producing dependable and yummy software[7]. This is done by making sure code is easy to read and understand, that it is logically sound. There are plenty of rules to help each of these, some of which are sometimes contradictory.

Clean code should be easy to read, leaving the reader or user with a clear understanding of what's happening, rather than having to dig one level deeper to understand ("one more thing to worry about")

Unit tests are useful on many levels with regards to code. They validate code and therefore, its function. They allow other people (including future-self) to change code with less stress. They force the writer to structure code in a way that is testable, which forces some logic in the code. They validate that the code is modular enough[3]. Test coverage can be checked using the "mutation testing" approach: change each line one by one and validate that a test breaks[8].

The SOLID principles are a set of principles

The onion architecture.

Separation of concerns

Factorizing (i.e. putting similar code into the same function), and in particular DRY, is more complex than meets the eye: the coupling created by having a common piece of code serve two usages might be satisfying at first but create complexities down the road, that's especially true when the usages "look like" but are not identical at a conceptual level. Some advise to first duplicate the code, then group it if it gets reused[2].

Object calisthenics[1] are a set of rules aiming at code readability. They orbit around the concept of keeping things simple and small: one level of indentation, of object depth, small classes, and functions, encapsulation, etc. Decomposition into small bits also arguably makes it easier to delete code later[2].

Code smells are a set of indicators that something is wrong with the code[5]. An analysis[4] of when these are created in code indicates that they're usually appearing from the inception of the program, and are accentued under pressure. This highlights the importance of checking for these throughout the project, through automation and code reviews[6].

against clean code

There are detractors of Clean Code. One argument is saying that it is usually a useless cost. Another that the recommendations are not clean[10]. My take is that the main reason for writing quick & dirty code is when it doesn't require guaranteeing further modifications (either because working on disposable code, or through low ethics - "the next person will deal with it")

links

Conceptual integrity helps code cleanliness.

[6]: Code reviews are very useful to check for clean code and obtain cleaner code.

references

Haoda Wang / This is What Peak Hello World Looks Like is an example of whatever the opposite to KISS is

[7]: Butler Lampson / Hints and Principles for Computer System Designref discusses STEADY (goals) ART (techniques) and AID (process) {TODO: complete article}

[8]: Hernan Wilkinson / Mutation testing is an approach to validate that test coverage is sufficient: modify lines one by one, if test doesn't break then tests are not covering the "surviving mutant", and it needs to be killed. (i.e. improve coverage.)

[9]: Uncle Bob / REPL driven designref even Bob gets caught once in a while.

[10]: Qntm / It's probably time to stop recommending Clean Code :

[...] the major problem I have with Clean Code is that a lot of the example code in the book is just dreadful.