私流コードコメントライティング
2024-05-25 前提についてなどちょこっと加筆
コードを書いているときに書くコメントについて自分が普段心がけていることについて書いていきます。
記事のタイトルの通りあくまで自分がこう書いたほうがいいと思っていることなので、そのチームによってありがたいと思うコメントは異なるかもしれないが、参考になればというのとこれらの書き方へのフィードバックをもらえる機会になればと思っているので、思うところがあればコメントを残してもらえると幸いです。
今回対象とするのは、Doxygenやpydocのような特殊なコメントによりドキュメントを生成するツール向けのものではなく、普通のコードコメントについてです。
また、対象としているのは複数人開発でかつ、GitHub等のコード共有プラットフォームでコードレビューを行うような環境でのコードコメントについてです。
普通のコードコメントはコードの読み手に対してコードの意図を伝えたり実装の方針を伝えることにより、コードの意味理解を助けてコードの保守や変更を容易にするために書かれているものです。
一方でコードコメントもコードと同じくらい資産として残り続けるものなので、適切に書かれていないとコードの理解を妨げることになります。
このことを踏まえて具体的にどのような点に気をつけてコメントを書いているかを示していきます。
Copilotにコード生成を促すように書く
GitHub Copilotのようなコード生成支援ツールはコードのコメントを読み込んでコードを生成することができます。
このようなコメントでコード生成に成功する場合、コードとコメントの整合性が取れている可能性が高いため生成に成功した場合はそのままコードの理解を助けるコメントとして機能します。
もっともCopilotの生成機能は未だ発展途上であるため、生成されたコードが正しくないケースも多いので信頼できないので頼り切りにはしないようにする必要はありますがそれは別の話です。
個人的にはCopilotの生成機能に頼りたくなるタイミングというのはコードのコメントを書くといい感じになるタイミングと一致しているように思うので基準としてはいいのではないかと思っています。
このようなコメントを書くことは仮にそのツールを使わない場合でも、自分のコードを書くときの指針を整理することになりコードを書きながら「あれ？今ってどういうコードを書いているんだっけ？」みたいな事態になることを防ぐことにもなります。
TODOコメントは具体的に何をすべきかを書く
長い間開発されているプロジェクトでコードがTODOまみれになっていて、しかもその意図が理解しにくいというのはよく見る光景ではないでしょうか。
コードに問題があることは認識しつつも、一旦はそのままにしておくというのは製品開発においてまっとうな判断ですが、そのTODOコメントの意図がわからなければ消すべきなのか・このコードは再利用可能なのかといった判断が難しくなります。
そのためTODOコメントは具体的に何をそのコードの抱える問題について書かなければなりません。
以下は具体的に何をすべきかわかりにくいTODOコメントの例です
- 複雑なのでリファクタリングする
- どうリファクタリングするかが不明確。やっていることが複雑ならコードも当然複雑になるので、複雑なのはしょうがないことかもしれない
- どうリファクタリングするかのアイデアがあるのであればそれを書くべき、ないのであればそもそも必然的に複雑になっているのかもしれないのでコメントは書かないほうがいいでしょう
- あっているか自信がない
- ではどうやったら自信を持てるのかがわからずそのままになってしまう
- そもそも自信がないのであればその場でテストを書いたりして自信を持ったコードにした上でメインラインに取り込むべき
主観的な意見や抽象的な指示語は避ける
コードコメントは他人のために書くのであるため、自分にしかわからない恐れがある主観的な意見や抽象的な指示語は避けるべきです。
以下のようなコメントは避けるべきです。
- 気持ち悪いコードだけど仕方ない
- 気持ち悪いというのはあなたの感想ですよね？
- 気持ち悪いという感想を共有したところで読み手のアクションは変わりますか？
- 「なぜ気持ち悪いと思ったのか」「気持ち悪いからどうしたいのか」という点を具体化すればコメントとして意味があるかもしれません
- いろいろあってこうなった
- いろいろとは？例えば新しく入った新人が読んでもわからない
- その経緯が重要でコメントに書くには長すぎるというのであれば別ドキュメント等にして書き残してそこへのリンクを提供しましょう
まとめ
コードのコメントは他人のコード理解を助ける重要なものであります。一方で、コメントが不適切だとむしろコードの読み手の認知負荷が増えてしまいます。
そのため、自分の場合は書くべきポイントは絞ってメリハリのあるコメントを心がけています。
繰り返しになりますが、これはあくまで自分がこうしたほうがいいと思っているものであり違う考え方もあるかもしれません。
もし、この記事に対してフィードバックがあればコメントを残してもらえると幸いです。
Discussion
記事に対してフィードバックがあればってことなので。。。
まずはリーダブルコード（または後発の類似の本）を読みましょう。
そのうえで、コードコメント（リーダブルコードなら５章）で取り扱うブロックについて思いを馳せましょう。
自分がこうしたほうがいいと思ってることを書いた、ということ自体があなたの感想ですよね？と言われても仕方がないです（実際そう思っています）。
コメントを記録するにあたり、どこにどのようなコメントを残すか、はコードや組織の規模や習熟度に大きく依存するので、汎化して書けることはどうしても同じような内容になりがちです。まるで古いPythonのコードのように。
ここまでの理解を共有した上で、私は（私達は）このように考えている、ここは異なる考えを持っている、ということを示して初めてまともなフィードバックが得られるんじゃないでしょうか。
雑ですけど、
のようなコメントは、リーダブルコード的にはありです（P61かな）
読み手のアクションが変わりますか？の意味を捉えかねていますけど、前述のコメントを読んで、このコメントを書いた人はこのコードが気持ち悪いと思っていたんだな（常に過去形）を元に、読み手である自分はどう思うか、そこにアクションする必要があるか（自分も同じように気持ち悪いと思ったら直せないか考えるべきでしょう？他人が書いたとこだし見てみないふりしよう、なんてエンジニア的にダメでしょう）を検討するでしょう。
気持ち悪いがただの感想で、今はそうでもないならコメントを消すなり説明を書き直すなりすればいいですし、気持ち悪くないコードが書けるなら直せばいいし、今は時間がないなら TODO にすればいいし、それらを確認するためのアクションを起こすべきです。
そもそもレビュー時点でどうにかすべき話ではあるけど、それはこういうコメントを書くべきではない、という話ではなく、後で相談できるようにポイントしておこう、でいい、ということなのです。
書くべきではないことと、書くべきこと、を画一的に決めるのは大変むずかしいですし、ハイクラスエンジニアからしたらこんなコメント書くなよ、が、駆け出しエンジニアにしてみればなるほど、と思われることだってあると思います。
あなたの（勝手な）感想ですよね？って思われないようにするためにも、基準（リーダブルコードなど）を元に、これは同じ、これは異なる、を表現できるといいですね。
ありがとうございます。リーダブルコードは以前読んだことがありますが、リーダブルコードも絶対的なバイブルとは自分は捉えていないので今回はその手の本をあえて参照せず書きました。結局はああいう本も個々人の経験に基づく部分が多いと思っているので、そのような基準を示してもあまり変わらないかなあと
もしそういうことを考えてのコメントであれば、そういうことを具体化するべきというのが私の主張です。気持ち悪さはどこから来るのか、どうやったら気持ち悪さを解消できるのか、がわからないと読み手からするとノイズでしかないです。まさに
ということを「気持ち悪い」という抽象的なコメントを残す前にやるべきでは？という話ですね
こういう考え方もあるかもしれませんが、後で相談は一生相談されない傾向にあると思っていて、それならばコードレビュー時点で解消する・諦めてそのままにするというのが私的には嬉しいかなと思います（あと今回の記事の前提としてコードレビューがある複数人開発というのがあることを書き忘れていました。コードレビューのない個人開発であとでOSSにする、みたいな場合だと話は変わってくるかかもですね）。
もし、その気持ち悪いという感想がほぼ全員で共有できるようなものであるのならば、コメントを書かずとも自然とそういうアクションをとるという流れになるでしょうしね。
そうですね。なのであくまで「私流」とつけてこういう考え方もあるよ、という紹介でチームの中で抽象的な感想でもコメントで共有したいと思うならそうすればいいとは思っています。極端な話、リーダブルコードでさえあなたの感想と言えてしまうわけで、この手の話はこういう考え方もあるよねといろいろなものに触れた上でチームや個人の中でこれといった哲学を構築していくのがいいのではないでしょうか？