自己文書化コードを書いているのなら、コメントは必要ないと思っていました。しかし、私はコメントを書いていることに気づき、それらが本当に役に立ったと感じました。私が書いているコメントの数とその内容を確認するために、過去6年間のgitコミットを分析するスクリプトを作成しました。合計で、承認された行の7％にコメントが含まれていました。この投稿には、良いコメントと悪いコメントとしてカウントされるものの詳細と、私のスクリプトからの追加の統計があります。
Javadocは最も役に立たない
コメントに懐疑的だった理由の1つは、Javadocスタイルのコメントが優勢だったことです。このスタイルのコメントは他の言語にも存在します。これが私が思いついたPythonの例ですが、これはこのスタイルの代表的なものです。
これらのコメントのほとんどの問題は、それらがほとんど情報を伝えないことです。多くの場合、メソッド名とパラメーター名を数語で繰り返すだけです。これらのコメントは、外部に公開されたAPIに役立ちますが、すべてのソースコードにアクセスできるアプリケーションでは、ほとんど役に立ちません。メソッドが何をするのか、またはパラメーターの有効な入力範囲は何か疑問に思っている場合は、コードを読んでその機能を確認することをお勧めします。これらのタイプのコメントは多くのスペースを占有しますが、特に価値はありません。
自己文書化コード
Javadocコメントを書く代わりに、メソッド名と変数名を最大限に活用するのが最善です。使用するそれぞれの名前は、それが何であるか、そしてそれがどのように行われるかを説明するのに役立ちます。1つの大きなメソッドではなく、多くの小さなメソッドを作成する理由の1つは、ここで説明した説明的な名前を使用する場所が多いことです 。
コメントするとき
自己文書化コードを書くことは、長期的にはあなたを助けます。ただし、より多くの情報があると役立つ場合があります。たとえば、以下のコードでのダイヤルゾーンの使用に関するコメント：
別の例：
「何ではなく、なぜコメントを書く」というアドバイスをよく耳にします。これはおそらく私のコメントのほとんどをカバーしていますが、これは私がいつコメントするかについて考える方法ではありません。代わりに、私は通常、ドメイン内または実装の実行方法のいずれかに特に注意が必要な場合にコメントを書き込みます。
「コメント不要」の群衆（私がかつて所属していた）からの標準的なアドバイスは、コメントする必要がないようにコードを書き直すことです。ただし、これが常に可能であるとは限りません。ドメインが複雑すぎる場合があります。コメントを追加する場合に比べて、コードを書き直す作業が大きすぎる場合があります。
コメントに関するもう1つの不満は、コメントがコードと同期しなくなるため、コードを支援するのではなく、コードの理解を妨げることです。それは時々起こりますが、それは私にとって大きな問題ではありませんでした。私が分析したほとんどすべてのケースで、コメントはまだ有効でした。彼らもとても役に立ちました。これらのコメントの1つに出くわすたびに、私はそれを書いたことをうれしく思いました。あなたが解決している問題の詳細とニュアンスのいくつかを忘れるのに時間はかかりません、そしていくつかの追加の文脈と説明でコメントをすることは素晴らしかったです。
コメントとしてログに記録
説明メッセージを登録すると、景品コメントがもらえる場合があります。以下の例では、ログステートメントが何が起こったかを説明しているため、コメントは必要ありません。
コメント分析
すべてのコミットに含まれるコメントの数を最初に確認することを考えたとき、すべてのPythonコミットのコメントを見つけるには1行で十分だと思いました（＃でコメントするだけです）：
git log --author = Henrik -p | grep '^ + [^ +]' | grep '＃' | wc -l
しかし、私はすぐにもっと詳細が必要だと気づきました。行末コメントと行全体コメントを区別したかったのです。また、「コメントブロック」（コメントの連続行）がいくつあるか知りたいと思いました。また、テストファイルを分析から除外することにしました。さらに、コメントアウトされたコードがそこに到達したことを確実に除外したいと思います（残念ながら、そのようなケースがいくつかありました）。結局、分析を行うためのPythonスクリプトを作成しました。スクリプトへの入力は、git log --author = Henrik-pからの出力でした。
出力から、追加した17817行のうち1299行にコメントが含まれていることがわかりました。161の行末コメントと464の1行コメントがありました。最長のコメントブロックは11行で、3行以上連続したコメントブロックは96件ありました。
結論
私は以前、名前の付いた関数を書くことはコメントが不要であることを意味すると思っていました。しかし、実際に行ったことを見ると、コードの複雑な部分や直感的でない部分にコメントを追加する傾向があることに気付きました。プログラムのこれらの部分を再訪するたびに、コメントを追加する努力をしたことをうれしく思います-それらは非常に役に立ちました！