5S Qualities of Well Designed, Well-Factored Code

The other day I was trying to explain to someone the properties of code that is well-factored and found myself using aliteration with 'S' words. That made me wonder if they were equivalent to Lean's "5S", which is as follows:

• Seiri (Sort) - Organize the work-area, leaving only the tools and materials necessary to perform daily activities


• Seiton (Straighten, Set in Order) - the orderly arrangement of needed items so they are easy to use and accessible for “anyone” to find.


• Seiso (Shine) - Keep everything clean and swept. Don’t allow litter, scrap, shavings, cuttings, etc., to land on the floor in the first place.


• Seiketsu (Standardize) - Creating a consistent approach for carrying out tasks and procedures. Orderliness is the core of “standardization” and is maintained by Visual Controls.


• Shitsuke (Sustain) - the discipline and commitment of all other stages. Without “sustaining”, your workplace can easily revert back to being dirty and chaotic. That is why it is so crucial for your team to be empowered to improve and maintain their workplace.

Does the above apply to the structure and content of the code itself? Have you ever come across code that is truly well-factored? I don't just mean correct and that it follows coding standards, I mean the structure of the code itself not only had such clarity of thought and order, but it also had all the qualities that we like to think of that make the code changeable/malleable with ease. Here is what I think those qualities are:

• Sufficient scope (content & functionality) – The code implements only that which is necessary. It doesn't have more content than needed, or more behavior or interfaces or abstractions than needed. It is "just enough" code to get the job done, while still possessing the other properties below. XP ensures this by taking the “next most important” requirement, creating only just enough content (spec, requirements, even branches) that can be implemented for current activity in the current workspace. Then write only “just enough” code to pass the test (then you refactor).


• Simple, clean code – The code isnt just "Lean" in its content and functionality, but also in its structural design. Dependencies and duplication are minimized while clarity, cohesiveness, and conciseness are maximized. In XP, once the code result is “sufficient” in content & correctness, we refactor to simplify the structure and dependencies as much as possible.


• Supple design – This comes from the chapter of the same name in Eric Evans Evans' book Domain-Driven Design. Supple means pliant, malleable, limber, yielding or changing readily. Code that is well-factored is at once so simple yet sufficient as to be firm yet flexible. Yet the flexibility comes not so much from what you added as from what you left out and how you organized it. It is more than just simple and sufficient, there is an inherent model or "theory" of the program inside the programmer's head, and that structure and intent are clearly conveyed and deeply realized by the code and somehow manages to incorporate the subject domain in it as well. Evans cites patterns of supple design like: Intention-Revealing Interfaces, Side-Effect-Free Functions, Assertions, Conceptual Contours, Standalone Classes, Closure of Operations, Declarative Style of Design.


• Serviceable product – Making the code easy to change isn’t enough. Use coding standards too. But beyond that, ensure that what is delivered from the code is serviceable, so that it is ALSO quick & easy to (re)build, (re)test, commit/merge, stage, release, configure and install/upgrade/deploy. It’s not just the code that needs to be quick and easy to change, it is everything that needs to be done to deliver change to the consumer in order to realize its value.


• Sustainable team velocity – Okay, I'm cheating a bit here because this last one is really about the process used to attain the other 4 qualities above. It's not just the code & product that needs to be sustainable (from a business-perspective and from a support/maintenance perspective) but the process that the programmers follow. On the one hand it must necessarily be disciplined, and yet it needs to be something that does not force them to work at or above their capacity for any significant time. The process should be sustainable and renewable so that the discipline is relatively easy to sustain and in fact gets easier over time, resisting "burnout" as well as the temptation to fall back into bad habits.

So that's my "5S" for code/design structure! It's not quite as pithy as saying "lean, mean, keen, clean & green." The thing is, I'm not so sure my five S-words really do map all that accurately to the 5S of Lean (and I'm not sure I should try to make them either). What do you think?