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.

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