この記事で主張したいことは、以下の2点です。
- あえて実施していない処理が存在する場合は、ソースコードに「処理Aは理由Xのため、このユースケースでは実行しない。」など、判断の背景をコメントで残すことを推奨したい。
- 判断の背景が長文になる場合は、別のドキュメントとして残してほしい。
背景
あるシステムをメンテナンスしている時に、気になることがありました。
そのシステムの多くのサービスでは、リクエストを受け付けた時に特定の外部APIからデータを取得して、リクエストパラメータと照合する。
これにより、リクエストパラメータの正当性を検証する。
しかし、ごく一部のサービスだけ、この検証が実施されていない。
この処理を見た時、私は実装漏れだと思いました。
気になったことは確認しなければ気が済まない性格なので、折を見て古株のメンバーに実装の背景を確認しました。
それに対する回答は
その2つのサービスは
・実行される頻度が他のサービスに比べて高い
・応答速度を重視したい
・仕様上、不正アクセスされるリスクが低いので、異常なリクエストが渡される可能性も低い
ので、『あえて』その検証を実施していない。
理由を聞けば納得できます。
しかし、実装漏れは、開発において十分起こり得るため、なかなかに初見殺しでもあるなと感じました。
問題点
特定の処理を実装していない理由が、ソースコードコメントやドキュメントとして明記されていない場合に、想定される問題点には以下のようなものが考えられます。
- 背景に記載したように、余分なやり取りが発生する。
- 開発者が、仕様を理解するのに苦労する。
- 開発者が、善意でタスクを切ったり改修を始めたりする可能性がある。
「なぜ実装したか」に比べて、「なぜ実装していないか」は記録されにくいと感じています。そのため、複雑なシステムほど意図が埋もれやすいのではないでしょうか。
解決策
- 『あえて』実装していない処理があれば、その理由や背景を、ソースコードコメントやドキュメントとして残す。
シンプルですが、これが非常に効果的だと考えています。
『あえて』がポイントだと考えています。
全ての理由や背景を残すことは、可読性と実装効率を低下させるうえに、作業量的に非現実的です。そのため、重要な理由や背景に限定して残すのが良いです。
ウォーターフォール型で開発をしている場合は、設計書に記載しておくのも良いかもしれません。
アジャイル型を採用している場合も、仕様をドキュメントに残してGitHubで管理しておくと、後から参照しやすくなります。
これは、新規に参画される方のためだけではありません。
ソースコメントやドキュメントに残す作業は、正直なところ手間はかかりますが、未来の自分のためでもあります。
また、最近は何らかの生成AIを活用して、仕様検討・不具合修正・機能追加などを行う機会も増えてきました。生成AIの作業精度を向上させるという意味でも、適切なソースコードコメントやドキュメントの重要性は高まるでしょう。
参考図書
ソースコードコメントに関する参考図書としては、「リーダブルコード」で非常に参考になる解説がされています！
- 5章 コメントすべきことを知る
- 6章 コメントは正確で簡潔に
の2つの章が、ソースコードコメントに関する解説です。特にこの記事と相性が良いのは、「5.3 読み手の立場になって考える」の「ハマりそうな罠を告知する」という項目です！
その他の章も含めて非常に面白い本なので、ぜひ手に取ってみてください。
以上
