notes/docs/professional/software-development-practices/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.

Submit your final draft, not your first draft.

Clean up code before merging it.

Developers don't always get the opportunity to go back and clean up messy code after it has been merged in. As far as business is concerned, the work is done, move on to the next work item.

1. Write code that works.
2. Refactor it to make it maintainable.

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.