Create coding-practices-for-teams.md

docs/programming/general/coding-practices-for-teams.md

@@ -0,0 +1,47 @@
+# Coding practices for teams
+
+## Write boring code.
+
+Developers read code far more often than they write code, so code should be
+easy to read and understand.
+
+- Follow existing coding patterns so that code looks familiar to developers.
+
+## Use comments to document why code exists.
+
+**Don't** use comments to translate self-explanatory code.
+
+This isn't helpful, adds noise to the code, and means that future devs now have
+to maintain these comments as the code changes.
+
+```php
+// Create golem.
+$golem = Golem::create();
+
+// Set golem type to clay.
+$golem->setType(GolemInterface::TYPE_CLAY);
+
+// Raise golem.
+$mage->raise($golem);
+```
+
+**Do** use comments to explain to other developers (including your future self)
+_why_ some logic is there.
+
+```
+// The summoner mage needs a clay golem to slow monster attacks against the
+// mage's other minions and party members.
+$golem = Golem::create();
+$golem->setType(GolemInterface::TYPE_CLAY);
+$mage->raise($golem);
+```
+
+**Do** use comment to explain hard-to-read code.
+
+e.g.
+
+- Regular expressions.
+- Calls to weird APIs with complex inputs.
+
+Comments **should** add information that a reader might not have while they are
+reading the code.