Be explicit about your code base style and software design

Imagine you start at a new workplace or a project you haven't had previously worked on.
Checking out a code base can be tedious and it can be unclear what to expect from it.

Some questions come to mind:

• Where can I find the important things?
• Why isn't this framework replaced by something modern?
• Do I need to install something to make it run?
• ... there can be many more questions arising.

It is good to understand early on what practices are followed and what design is aimed for. There is even more one would like to know or what one can expect from that code base.

As a project maintainer you can help with that. Write down what goals you are aiming for and which practices support you to reach this goal.

Write it down. Make intentions clear. Be explicit.

During my journey in software development, I once worked in a team where we did that. It helped a lot. We got less questions on why we chose what and if we considered that.

README example:

• We are using <formatting style XYZ> to have a consistent format throughout the code base and use this <XYZ formatting tool>.
• We make use of linting to be able to mitigate common problems and use <linter XYZ>.
• We use unit tests for testing business rules.
• We use integration tests to check if the pieces fit together.
• We organise our code following hexagonal architecture, to separate our domain from frameworks and other details.
• We use domain objects instead of generic ones, e.g. Username object instead of plain String,
• ...

We stated the software design goals and architecture even before we wrote any code, so that we knew immediately what we are looking for when we start the work on the code. It supported us to have less things in our heads while we implemented.

A different way would be to write these things down as architecture decision records (ADR) inside the repository itself.

The decisions don't need to be architecture related, they can be any decision in the context of the code base's repository. You can document dependency choices, software designs, and tech debt; don't forget to include pay back plans.

With these, anyone who checks out your code can have a faster introduction to it, and understands from the start what things are considered important and intentionally not considered.

This also helps to have better code reviews, since expected things are explicitly stated already; like code style, linting, design patterns, and architecture. This should speed things up and have less comments about these items that got already decided.

You can focus on the details that are important.

To make the implicit explicit helps to communicate the context and why things are as they are.
Your future self and colleague will be thankful. :)