Having a structured plan for the codebases in your project will help extend their lifecycles. It will also help those using the code to more easily manipulate them to fulfil new business requirements whatever these might be.
To that end, I wrote this document as a guideline for my company, feel free to adopt, adapt it or use it as a basis your own.
Lists the sections in this document, hyperlinking them for easy navigation.
- Code quality
- Type Safety
- Unit Tests
- End to end Testing
- Deployment mechanisms
- Error reporting
- Code safety
- Appendix 1: Background to Projects
I have tried to answer the question “Why does this document exist?” and clarified why this is a helpful document to maintain.
For each of the sections mentioned in the index, give a high level overview or history, outline what objectives you have for the future, show the current status of those objectives and explain what has been done so far:
Example of Section 1:
1. Code Quality
- Use the same linting rules for all packages where possible
- Use language-specific coding styles (eg. functional over classes)
- Use a single compiler where possible and follow the latest ECMAScript standards
Not started / In Progress / Completed / Cancelled
At the end of the sections, I have two appendices: one which has an overview of each codebase, and another that builds on the section on “Standardization of Code”.
Example of Appendix 1 (Background to Projects):
This application provides a service to …
Pipeline: Github Actions
Code quality: Good/ Bad / Reasonable
Tests: None / Some / E2E only / Unit only
Status: In development / In production / Being renovated / Up to date
Many thinks to my friend Josh Farley for this one. It’s a table which hilights decisions on code quality and standardisation that aren’t covered by Prettier or the AirBnB Style Guide.
|Files should be snake, eg.Good:
|This makes files easier to scan quickly in the source view
|Files should not be nested beyond 2 levels.Good:root/src/component.jsBad:root/src/components/utils/frontend/component.js
|This makes it much easier to discover components and avoids duplication
|Use American english spelling for variables and function names
|Simplifies code for non-native speakers. One standard is better than none.