Documentation

Keep your project and code base documented to make sure updates can be managed smooth over time.

Code comments

For the most of the time, code should be self explanatory. But of course, there are cases where some comments are appropriate. Think if you would return in a year to your code and where it might be hard to follow what happens.

Readme file

Each repository should have a README.md file. This file should have information about:

• Which Git workflow is used

• How to get the project up'n'running for any developer

• Any project specific information that is valuable for developers

• How to deploy

• Information on what keys are used and how to get them

Passwords and keys

No passwords or keys should ever be committed to the git repository. If a .env file is used, it should not be committed to the repo, but instead have a .env-example file (without real keys).

Any keys or passwords should be kept in a secure way and preferably with a service like 1Password.

It's important that all keys and password are stored somewhere to make sure future developers have access to them.

Project documentation

Other information about the project should generally be documented in a project management system.

AI Instructions

Projects should include an AI instructions file to guide AI assistants (like GitHub Copilot) in generating code that matches our standards.

For Copilot, this is currently done via a copilot-instructions.md in the repository. This file should include:

• Preferred languages, frameworks, and libraries (e.g. React, Laravel, Tailwind).

• Code style and naming conventions.

• Architecture rules, such as “separate business logic from controllers.”

• Testing requirements.

• Documentation expectations.

This file acts as a guideline for the AI, much like a linter or style guide does for humans.