Techincal direction

This document covers the technical direction and high-level development principles that should be observed by all contributors of the project.

Can be thought of as an informal social contract and outline of the intended development culture, that can be assessed by potential contributors to see if this is the kind of environment that would be suitable for them and their preferred ways of working.

KISS, YAGNI

• Don't create abstraction layers/custom libraries preemptively, thinking that they might come in handy in the future. Focus on the problem at hand and keep solutions scaled to what is actually needed right now.
• It is OK to refactor as requirements evolve.
• Reject Complexity, Embrace Grug

Standards

• Any part of the codebase should look the same as any other, and seem as if the same developer had done it, avoiding individual preferences.
• Standards aren't meant to please everyone or get everyone to agree on everything. They are just to make sure everyone can work with each other in a consistent and effective way.

No silver bullets

• When something seems like a perfect solution and too good to be true, it may be because it is.
• Discuss great ideas with others to gain a perspective of the potential wider implications.

Team

• Great software is made by great teams, not great individuals. The fabled "10X rockstar unicorns" aren't a reliable long-term dependency to build a project's workflow around.

Documentation

• Everyone should work to make themselves easily replaceable. Any other developer should be able to approach any area of the codebase and be able to quickly and easily start being productive, without first needing to spend a lot of time and effort to build an extensive mental-model of that area.
• No gurus/oracles. There shouldn't be individuals with exclusive knowledge over certain domains who are the only ones who know how those things work. This presents a technical and operational risk should they not be around any more (leaves the project, on holiday, hit by a bus etc.).
• Dispelling the "documentation is pointless" myth.
  • This sentiment is often accompanied with the reasoning that "If I want to see what the code is doing, I can just look at the code", or "Documentation just gets out of date with the code too easily".
  • These are code-centric ways of thinking that treat the current implementation as a supreme authority, and documentation just as an imitator.
  • The real purpose of documentation is to serve as a record of intent, describing a developer's thought process in the moment. It should rarely be about describing what the code itself is doing, as indeed you can just look at the code to see that. Consider the following questions as things to note in documentation:
    • Why did you go with the current solution?
    • What other solutions were also considered, and why didn't you choose each of them? Which ones did you try and what problems did you run into with them before you arrived at your current solution?
      • This tells other developers what they can avoid trying when they look at something and where their response may be "Oh, that way of doing it isn't ideal. I can just change it be be like this instead!", and end up trying something that was already tried and doesn't work.
    • What other solutions were also considered (such as potential improvements that could be made), but you just didn't get around to trying?
    • What are the problems with this solution, but that you couldn't find a good way to fix?
    • What caveats do others need to keep in mind when making changes to an implementation/what side effects may there be. What specific requirement/design notes should be mentioned about an unintuitive piece of code?
  • So yes, bad documentation can be pointless, but good documentation often is critical.