Code style¶

We use Prettier (which is an opinionated code formatter) for the frontend and the Cargo toolchain, including rustfmt for the backend. They enforce consistent formatting throughout the codebase. Using consistent formatting makes the code easier to read for all contributors and is therefore enforced by our continuous integration pipeline checks.

Going beyond formatting, we:

• Prefer simple code over performant code, unless absolutely necessary (read more).
• Write self-documenting code (read more).
• Avoid abbreviations and technical nomenclature, within reason.
• Co-locate code that is related (read more).
• Avoid premature abstractions (read more

The most important point of all is the last one. It's often tempting to introduce an abstraction when we notice duplicated code. Sometimes that's appropriate, but often it is not. Before abstracting away duplicated code ask yourself:

• Are these pieces of code guaranteed to stay the same in perpetuity?
• Are these pieces of code located close to each other or are they parts of completely different code? Co-located abstractions will be easier to change later down the road, while a change to a separate file like utils/usefulFunction.ts could cause unforseen changes throughout the application.
• Will this need to be parametrized in the future by adding props and conditional logic? A good example could be how we previously added an isNolla prop throughout our application to many different components so that they could then be used on our https://dsek.se/nolla pages too. A better solution would be too simply copy the code since these components are obviously not the same. If they truly were, we wouldn't have to add a prop simply to cater to their new use case.

Guidelines¶

Simplicity is key. We are a small team working part-time on this project. We need to be able to onboard new developers quickly every year. We want everyone to be able to contribute to the project, regardless of their experience level. Therefore, complex features should be avoided and we should instead try to find simple and understandable solutions. Additional libraries and frameworks should be avoided unless they undeniably make our lives easier. Simplicity is key to both the longevity of the project and our ability to create a community of members who can contribute to the project.

Stability is equally important. The entire D-guild expects our systems to be operational at all times and we need to be able to quickly fix any issues that arise. This means that we avoid using experimental technologies and libraries. We also avoid using technologies that are not well supported by the community. Without stability, we risk losing the trust of our users.

Also consider documentation; if there is any chance someone else would ask "why" or "what am I looking at", please document why the code was needed respectively author a README.md file which explains the structure.