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

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.

// 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.