はじめに
「クソコード」と呼ばれるコードが生まれる理由は様々ですが、本来コードを読みやすくするはずのコメントが原因でソースコードの可読性が下がる事もあります。
何となく直感でコメント内容を決めていくと可読性を下げるコメントを残してしまっているかもしれません。
実務で携わった案件でも、コメントのせいで処理が追いづらかったり、コメントと動作内容に齟齬があり、騙されそうになる事もありました。味方に後ろから切られる気分でした、、、（汗）
そこで本記事では、「可読性を上げる為のコメント」について考えてみたいと思います。
記事の目的
・コメントの目的、残すべきコメントを知ることでコードの可読性を高める。
優れたコードの定義
事前に今回目指す「優れたコード」の定義を明確にします。
「優れたコード」とは、他人が最短時間で理解できるコードと定義します。この他人には何ヶ月後かの自分も含まれています。
コードを書いている最中は実装の周辺知識などが豊富にある状態ですが、何ヶ月後かにその箇所のコードを読む時はそのような前提条件がない可能性が高いです。
開発で最も多くの時間を占めるタスクは既存コードを読み、理解することです。
その為、他人がが理解しやすいコードを目指す必要があります。
理解しやすいコードの要素は様々ありますが、本記事ではソースコードのコメントという視点から考えてみたいと思います。
コメントの目的
コメントがあってもなくてもソースコードは同じ動きをします。
むしろ闇雲にコメントを残すと、コードの視認性が下がり悪影響を与える事すらあります。
このような不要なコメントを残さないように、コメントを書く目的を常に意識しておく必要があります。
コメントの目的は、ソースコードの書き手の意図を読み手に知らせる事です。
背景知識のない読み手になぜそのようなコードなっているのか、前提知識がないと理解できないものをコメントとして残す事で、読み手側にコードの意図を伝える役割があります。
不要なコメント
実例を挙げながら、視認性を下げるコメントを見ていきたいと思います。
これらは私が新人研修のレビューや、案件内で実際に出会い不要と感じたコメントです。
変数名・メソッド名を説明するコメント
名前から意味を読み取れない変数、メソッドに対しコメントで説明を加えているコードがあります。
この場合は、コメントで補足するのではなく名前を意味あるものに変更しましょう。
// 姓 $a = '田中'; ← 変数名を意味のあるものに変更する $last_name = '田中'; ← コメントがなくとも変数名から意味を汲み取れる
コードの再翻訳
ソースコードから読み取れる内容をコメントに残すべきではありません。
コードの視認性が下がる上に、該当箇所に変更が加えられた時にコメントを修正する手間も発生するなどの弊害があります。
例)
// a と bが等しい場合
if ($a === $b) {
}
コードの変更履歴
過去に携わった案件でコードの修正履歴、変更者などをコメントとして残しているプロジェクトがありました。
コミット情報で確認できるので必要ではないかと、、、
public function taxAmount($item_price)
{
return $item_price + ($item_price * 0.1); // 2020年1月bugfix ◯◯
}
必要なコメント
なぜそうなっているかの説明
本来はこうあるべきだと考えられる処理だが、（〜の理由で）あえてこのようなコードになっているなどの背景はコメントに明記しましょう。
なぜそのような選択をしたのかわ本人しかわかりません。
なにもしない事の宣言
何もしないのコメントとして残す以外方法がありません。
コメントを残す事で意図して処理を書いていない旨を知らせる効果があります。
try {
...処理...
} catch (\Exception $e) {
// do nothing
}
コードの欠陥をメモして置く
欠陥を認識しているがどうしても手が回らない場合など、せめて改善が必要な事をメモしておく事で将来的な修正に備えてコメントを残す事もありかと思います。
その際にはメモルールをチームで統一して決めておくと重宝します。
例）メモルールの一例 TODO：あとで手を付ける FIXME：既存の不具合があるコード XXX：危険！大きな問題がある
参考
本記事はリーダブルコードを参考にしています。
本書には、ソースコードを「いいコード」にする為のノウハウが詰まっています。経験が浅い方でもすぐに使える内容も含まれるのでぜひ一度読んでいただきたいです！
