...or, what is the best practice for capturing best practices?
Note that I am not asking what these best practices are; these will vary from person to person, team to team, language to language, domain to domain.
To clarify, I am curious if there is anything approaching a standard for capturing coding best practices such as...
Example best practices
- Naming conventions
- Comment tags used
- The holy war of curly brace positioning
- Logging policies
- Restrictions or emphasis on various design patterns
- When to break out a separate function, file, or library
...and so on. Obviously this list can go on forever!
What do I mean by capturing?
I mean encoding these best practices in a way that is the most useful.
Keeping this information as so-called tribal knowledge is a weak form of capturing, in that it is prone to inconsistency and data loss, and is not easily enforced.
Maintaining checkstyle configuration is a strong form of capturing, in that it is very explicit and easily enforced. However, it is not very flexible and fails to capture higher-level thinking.
Solutions I am aware of
- Amalgamate over classics like Clean Code or Code Complete, which is not customizeable or domain-specific,
- Leverage tooling like checkstyle, which can't capture the nebulous, or
- Create custom documentation.
Is there something better? Thank you!
