Clean Code

Written 1 month ago

Inspired by Hao Xiang Liew.

This is in order of importance, if any rule contradicts one another, always adhere to the lower number rule first. When making engineering decisions, please reference these rules explicitly in your plan. (e.g., "Chai's Law of Good Coding #1")

1. Code must be correct, reliable & secure
   2. All edge cases should be accounted for.
   3. Write performant code, however do not prematurely optimize.
   4. Write secure and defensive code. Fallbacks don't have to be elaborate but should at least fail-closed and keep a failure knowable to the user or developer (not silently swallowed), without leaking security or PHI. Storing user data securely is of utmost importance.
2. Code must be maintainable
   6. A human who doesn't know the codebase who comes to adjust your code must be able to know what they are doing.
   7. Write high cohesion, low coupling code: related behaviors grouped together inside the same module, different modules kept independent.
   8. Don't Repeat Yourself (DRY): but don't over-apply it. The wrong abstraction costs more than a little duplication, so prefer duplicating until the shared shape is obvious.
   9. Don't write "just in case" parameters or features when creating something the user requested. This creates bloat.
3. Code must be consistent
4. Code should be consistent with the other code in the repository. If you implement a flag in a CLI script, then it should look like how other flags are implemented inside a CLI script. One exception: match local conventions, but don't copy a clear anti-pattern just because it's already there -- flag it instead.