OSSをやり始めて変わったコメントに対する考え方

unvalley
·

大学院のころから、あるOSSのリポジトリにコミットし始めました。OSSという言葉は定義もありますし、主語が大きいと思うので、ここでは僕が関わったものに限定します。

OSSをやってきた中で、色々なことを学びました。その中で特に大きかったのは、コメントについてです。ある程度複雑な実装をしたとき、コメントを書いてくれとよく言われました。

以下において、命名と型定義とテストをちゃんとやるのは当然とします

コメントがあると、意図が伝わる確率が高まるケースが多いです。意図が伝わる確率が高まると、コードを読む・理解する速度が上がります。すると、実装への着手スピードも上がります。関数の説明を特定のコメント形式(JSDocやrustdocなど)として書くと、エディタに依りますが開発体験を向上させられます。ソフトウェアエンジニアリングの文脈では、ドキュメントの重要性が語られることが多いですが、コメントはドキュメントよりも保守と改善が容易だと思います。なぜならソースコードにもっとも近いためです。

以下のサイクルで開発ができると、コメントがメンテナンス性に寄与できると思います。

  • 実装者はコメントを追加していく

  • そのコメントを読んだ人がコメントを評価して、不要なら消す・足りてないなら追加する

自分は「意味の分からないコメント」に遭遇した経験が少ないです。なので、コメントは良いものであるというバイアスがあるかもしれません。処理に対して逐一コメントをしているようなコードは揶揄されますが、良い面もあります。例えばoxc-projectというlinter実装などでは、それが新規貢献者の助けになっているはずです(説得力弱いですが)。

コメントと実装の整合性は、型定義やテストと比較してCIでチェックするのが難しいというのは、その通りだと思います。とはいえ、その状況を鑑みても、コメントが保守できないチームが、なぜドキュメントが保守できるのでしょうか。仮にそのチームがドキュメントを保守可能であることを前提とすると、コメントのみが保守不可能になる説明は難しいと思います。「ドキュメントが保守できない組織であるため、コメントも保守できない」というのであれば、それは一貫しているのでよいと思います(書いていて胃が痛くなってきますが)。

業務においても、もっとコメントを書く人を増やしたいです。特にドメイン知識が求められるB向けサービスのコードなどでは、コメント量が増えてもよいと思います。

@unvalley
都合の良い解釈の模索