There's a lot of common best practices we try to follow within the team but that we don't necessarily document or have a formal way to enforced. e.g.:

• Use ::create() to instantiate new DataObject rather new- this is in debate to some extent
• Use the Injector to bootstrap services even for third party objects
• Explicitly require any API you call in your composer.json file

While technically those things are not essential, they generally lead to more robust code. By documenting those explicitly we can save ourselves discussion in peer review and encourage quality code in our OSS product and in our bespoke projects.

Acceptance criteria

• A list of best practices has been establish and make general consensus among core committers and the team.
• A page has been set up in the doc to record the best practices.
• The page makes clear that best practices can be overridden in individual circumstances and are not hard rules.
• Best practices are aimed towards both core modules and bespoke projects.

Notes

• We already have pages in the docs about coding conventions
• We might be better served explicitly forcing at least some of these through static analysis in CI e.g. via phpstan
• Once the card is done we should relay this to @jakxnz

PR

• DOC Update coding conventions #397