はじめに
・コードを綺麗に書くことに課題を感じている方。
・コードの保守性に興味がある方。
・チーム開発をしている方。
・リーダブルコードを知っている方、あるいは読んだことがある方。
※尚、この記事は続編を公開予定です。
リーダブルコードとは
より良いコードを書くための
シンプルで実践的なテクニック
参考文献: リーダブルコード
といったサブタイトルの実践向き、
IT擬技術参考書になります。
※詳細情報
| 著者 | 訳 | 発行元 | 定価 |
|---|---|---|---|
| Dustin Boswell(ボズウェル, ダスティン) | 角 征典 | O'Reilly Japan | 2400円+ 税 |
価値のないコメント
価値のないコメントは、
コメントしなくてもエンジニアが理解できるコメント。
コードから、すぐに分かることをコメントに書かない。
参考文献: リーダブルコード
※例としてPHPのコードを例にしてみる。
サンプルコード①
<?php
// コメントクラスの定義
class Coment {
private $coment;
// コンストラクタの定義
public function __construct($coment) {
$this->coment = $coment;
}
}
?>
※サンプルコード①について。
新しい情報を提供する訳でもなく、
読み手がコードを理解しやくすなる訳でもない。
参考文献: リーダブルコード
サンプルコード②
<?php
// 中略
//<------------------>
// 配列の1番目以降の要素を削除する
array_splice($lines, 1);
?>
※サンプルコード②について。
厳密に言えばこのコメントも「新しい情報」を提供していない。
コードを見ればどうのように動くかは分かる。
参考文献: リーダブルコード
コメントのためのコメントをしない。
コメントのためのコメントをしないとは、
コードをそのままコメントに使用すること。
関数の名前と、引数をそのまま文章形式でコメントに書き直す
参考文献: リーダブルコード
サンプルコード③
<?php
// 中略
//<------------------>
// $valueが1の時処理をcontinueし、それ以外は$valueを表示。
foreach ($values as $value) {
if ($value == 1) {
continue;
}else{
echo $value.PHP_EOL;
}
}
?>
コードの欠陥にコメントをつける。
以下、引用したので参考にしてください。
記法 典型的な例 TODO: あとで手をつける FIXEM: 既知の不具合があるコード HACK: あまりキレイじゃない解決策 XXX: 危険! 大きな問題がある
まとめ
・価値のないコメント
コメントしなくてもエンジニアが理解できるコメント
・コメントのためのコメントをしない
コードをそのままコメントに使用すること
・コードの欠陥にコメントをつける
※参考文献を参考にしてください。