Advent Calendar #16 - My guiding principle for building clean software

It's not always easy to decide where code should go. Especially when things need to go fast. In this post, I will share my guiding principle for structuring code into modules.

What is a software module?

A software module describes a subset of the actual project, that can compile and run. It can be imported into another software project and extended from others.

You can cut your packages the way you like. Microservices, for example, is one approach to cut your whole software into different modules.

When does code belong in a new package?

I like to follow the single responsibility principle of the S.O.L.I.D principles. It states, that each module, class and function should have just one responsibility.

Typescript example

|- TodoApp
  |- core
    |- repositories
      |- task.ts
      |- bucket.ts
    |- models
      |- task.ts
      |- bucket.ts 
  |- ui
    |- components
  |- firebase
    |- repositories
      |- task-repository.ts
      |- bucket-repository.ts

If I were to replace the Firebase implementation now with another one, for example, Appwrite, I would just create a new package, that imports the definitions of the core package and put the logic for Appwrite there. This is also a part of the so-called hexagonal architecture.

The UI module would then import core and appwrite.