48 lines
1.2 KiB
Markdown
48 lines
1.2 KiB
Markdown
|
# 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.
|