A living room with nice furniture placed with good amount of space to move around.

Software architecture is a known concept. This is a post about software interior design.

As a developer I spend my work days submerged in code. That is my work environment, together with all the tooling that come with it. For work to be pleasant it matters how the code is written. And just as software architecture, with its patterns and structure, come form the architecture of houses, there is now software interior design. I like to share some of my principles around it.

Free your rooms of things that distract and hinder you

  • Use version control to remove everything that is not needed as the code works now. No commented out code, no old classes that stick around just in case you need them again. Trust your versioning system.
  • Use a linter to make the code consistent.
  • Do not allow any errors, warnings or broken tests to stay in the code. It will dull your sense of order.

Create spaces that serve the ones using it well

  • Optimise your code for reading, you will do that much more frequent than you write it. (The interior design equivalent is that things should be easier to put away than to take out.)
  • Store things together that belong together. See what files are touched by a change. If you need to touch the code in a lot of places for one change, it is a design problem or too big changes.
  • Have a working pipeline. Make sure that you have an environment that you can run and test your code in.

Things that are cared for last longer

  • Update frameworks. Make sure that the documentation and readme is updated too.
  • Refactor the code while you modify it. Tests and a good IDE will do wonders.
  • If the code smells, you should probably clean it. It could need a bigger rewrite than what fits into the everyday work on new features.

Create a place that makes others feel welcome

  • Have a complete readme for setting up the project. Err on being too explicit rather than assuming that the one following the guide knows things they do not.
  • Let rules for the project be explicit. “Configuration as code” and linting are both also social contracts. Explicit rules can be challenged when new insights arrive (sometimes in the shape of new people). The rest of the time no-one has to spend energy on sticking to them if they are automated.
  • Use the business domain in the code. New people will have to learn both of them. If the knowledge about the business is explicitly expressed in the code, there is less to learn. And learning from one of the areas will make the other easier to understand.

Related texts

A single frosted leaf with clear contours and veins.

TDD in the context of writing code to be read

Wunder Baum hanging from a car window (Known as Little Trees in most English-speaking countries)

Wunderbaum testing