Points on coding standards
_As the system gets larger- it becomes harder to maintain, expand, and understand. Code quality and architecture are the main factors that can affect the complexity of the system — and if we make the right choices when coding, the system quality will improve. In the long term, we will be able to deliver more, faster, and better.
“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”
— Martin Fowler
If the system is not well maintained and has low quality, a large refactor will become necessary to continue delivering. Such a thing can be hard to get right, and we will likely want to avoid it, even if it means stopping adding new features to the part that is hard to maintain. Having good code quality can prevent (or reduce) that.
In the microservices world, different engineers will likely implement different services — the inconsistency that may occur due to different experiences, styles, and ways of solving problems — may make it hard to move between services. If each service would have a similar appearance and conventions, then the overhead of getting familiar with the code will reduce, and more focus will go to making business logic decisions, solving bugs, and optimizations.
What standarization can improve?
- The system will be more secure because common security mistakes will be documented and reviewed.
- You don't have to reinvent the wheel, so writing new tests is much simpler.
- The code uses consistent patterns and style, which makes it easier to maintain and extend.
- If your code is maintained and expanded correctly, it will be more reliable.
More benefits of having a clean and standardized code
- Helps newcomers quickly dive into the code.
- Easier integration with other teams.
- Better developer experience
- Improves delivery time and quality.
How can we preserve code standards
- PR reviews
- Team agreement
- Test coverage
- Linters / formatters
- Static code analysis
What standards you can imply?
Think about the weak spots of your system. Maybe you already have some implicit conventions that you can make explicit or change.
Example of things you can standardize
- Code structure and layers
- Code style
- Widely used naming
- Code comments
- README file
- Type systems
- Configuration conventions
- Third-party packages
- Services communication (REST / GraphQL / RabbitMQ / …)
- Well known conventions (HTTP status codes, language specific conventions, …)
- Automated testing (mocks / coverage / names / …)
- Schemas and validations
- Errors
- Error handling
- Observability
- Security manners
Questions to ask when writing standards
- How much time and focus do you spend when getting into a new service?
- How much time it take to create a new service?
- How much time it take to add new automated tests?
- Are you using old/deprecated third-party packages?
- Do you know which third-party packages you use in the system? Is it different for each service?
- When there is an issue in production, does taking a look at someone’s else code helps you understand the flow?
- Is it frustrating to write code in components implemented by other engineers?
- Using APIs written by other engineers is intuitive? Can you guess the parameters without prior knowledge?
- Do you trust every engineer in the team to not insert obvious security vulnerabilities?
- Is it easy for you to read the logs? Search for metrics?
Conclusion
There are many ways to standardize the code and there is no correct formula. Sometimes standardization is necessary to keep the code well-formed, and sometimes it isn't. It is up to you and the team to decide which aspects are important to agree on, and which should be open for the developers to decide.