58 lines
1.5 KiB
Markdown
58 lines
1.5 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.
|
|
|
|
## 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.
|