コメント書いてますか？

雑談

あなたは自身の書いたコードにコメントは書いているでしょうか？
常にしっかりコメントを書いている人もいれば、コメントがなくとも理解できるコードを書くべき、というスタイルの人もいるでしょう。
ちなみに僕はコメントは割としっかりめに残すタイプです。

今回は、僕が普段心掛けているコメントのマイルールを紹介しようと思います。
あくまで紹介なので、どのスタイルが優れている(or劣っている)といったことを論じるつもりはありません。
ただ、今の自分のコメントの運用の仕方に自信のない人や、他の人のコメントの書き方に興味がある人には参考になると思います。

基本的にコードを読むだけではわからないことをコメントする

「コードを読むだけでどういう処理なのかわかるように書く」というのは全く持って正しいです。
コメントをよく書く派の僕も、変数名やクラス名は極力わかりやすい命名を心掛けます。
コーディングに関する書籍や情報にも、似たようなことはよく書かれています。

ただ、実際に現場で開発をしていると、どうしてもコードを読むだけではわからない事情や背景があったりします。
具体的に例を挙げると以下のようなことがあったりします。

  • 環境依存の不具合等で、本来推奨されている処理が使えず、自前で複雑な処理を実装せざるを得なかった
  • 不具合の緊急対応等で、できるだけ早く問題解決する必要があったため、非常に汚い実装になってしまった
  • プログラミング言語側で同じ結果を返す処理が用意されているが、よりパフォーマンスを改善したかったため、あえて自前で処理を実装した
  • 技術的な理由で本来の仕様とは異なる実装だが、プロジェクトリーダー等のシステムに責任を持つ立場の人の了承は取っている
  • 原因不明あるいは解決が難しいエラーが発生していて、泣く泣くTry-Catchで握りつぶしている

開発業務の経験がある人であれば、似たようなケースに遭遇したことはあるのではないでしょうか？
全く事情を把握していないエンジニアが、このような事情が潜んでいるコードの修正を担当すれば問題が生じる可能性が高いことは言うまでもないでしょう。
コメントは単なる説明だけではなく、意図や文脈を伝える手段としても有用なのです。

処理の複雑さに応じてコメントを書くかどうかを決める

コードを読めばすぐに理解できるような処理に対してコメントを書くと、無駄に行数が増えるだけです。
例を挙げると以下のようなコードです。

int[] GetSquaredNumbers(int[] numbers)
{
  int[] squaredNumbers = numbers.Select(x => x * x).ToArray();
  return squaredNumbers;
}

引数のintの配列の値を、それぞれ二乗した値を格納した配列を返す処理です。
C#で書いていますが、C#を知っている人はもちろん、C#を知らない人でも大体何をやっているかは名前を見れば予想がつくと思います。
このようなコードであれば、コメントはむしろ邪魔になりえます。

一方で、ぱっと見ですぐに理解できない処理の場合は、極力コメントを書くようにしています。
ここで言うぱっと見ですぐに理解できない処理とは、複雑すぎてコメントを読んでも理解が難しい処理はもちろんのこと、少し行数があってコードを読むのに多少時間がかかる処理も該当します。
僕の場合は、5行以上コードを書いている処理であれば、その処理の概要をコメントに書いています。

TODOコメントに自分の名前を入れる

開発を進める中で、優先度の低いタスクやすぐに対応が難しいタスクが後回しになることがあります。
その際に該当の修正箇所にTODOコメントを付けることはよくあります。
未解決のタスクや改善項目をマークするために非常に便利ですが、適切に管理する必要があります。
僕の経験上、開発・運用期間がある程度長いプロジェクトは、大抵TODOコメントだらけになっています。
しかも優先度が記載されていないことが多く、何から手を付けるべきか把握するのも一苦労です。

そこで僕が考えたのは、TODOコメントに自分の名前を入れるということです。
例えば、単に「TODO: ○○の機能を実装する」だけでなく「TODO: yasunomono ○○の機能を実装する」と書くようにします。
自分の名前を書いているので、他の人が見てもだれが対応するか一目瞭然ですし、自分のタスクだという自覚もしっかり持てます。
さらに、自分の名前で検索すれば修正が必要な箇所がすぐに見つかるので作業効率も向上します。
そして、自分の名前が書かれたTODOコメントをすべて消化した時＝自分が対応すべきTODOはすべて完了、という論法が成り立ちます。

コメントのメンテナンスも欠かさない

開発・運用を続けていく中でコードが汚くなり、リファクタリング等のメンテナンスをすることがあると思います。
それと同様にコメントにもメンテナンスが必要です。

仮にコメントをメンテナンスせずに放置していると、コードの内容と一致しないコメントがどんどん増えていきます。
これはコードを修正するエンジニアに誤解を与え、コードの品質を著しく低下させる原因となりえます。

そこで僕が心掛けているのが、コードを修正した際に必ずその処理に関連したコメントも確認し、必要に応じてコメント内容も修正するというものです。
特に、他のコードからコピペして実装した際は、コピペ元のコメントが残らないよう気を付けています。

コメントはとても有用なものですが、適切なメンテナンスを怠ると逆に有害なものになってしまいます。
当たり前と言えば当たり前のことなのですが、意外と対応を忘れがちなので注意しましょう。
さらに言えば、他のエンジニアの実装のレビュー時もコメントの修正漏れがないかチェックができれば、よりシステム全体の品質向上につながります。

読む人が不快に感じる(感じかねない)コメントはしない

コメントの書き方は会社やプロジェクトによってかなり違ってきます。
ガチガチにルールが定まっているプロジェクトもあれば、何を書くのも自由な会社もあったりします。
前者の場合は、しっかりルールに従ってコメントを書けば何も問題はありません。
逆に後者の場合は、いくら自由にコメントを書けると言ってもあまりにはっちゃけすぎたコメントを書くのは控えましょう。

特に、特定の個人や組織に対する不平・不満等は絶対に書くのは控えてください。
基本的にはコードは内部の人間しか閲覧することはできませんが、それも絶対ではありません。
「外出先で仕事をしていて、うっかり他の人に見られてしまう」「システムをOSSにする方針となり、外部に公開することになった」「外部向けの講演・記事等で、コードの一部を紹介することになった」等は十分ありえることです。
いつ誰に見られても何の問題もないコメントを心掛けましょう。

また、これはめちゃくちゃ個人的な感覚なのですが、コメントに顔文字があると少しイラっとくることもあるので僕はコメントに顔文字はつけません(笑)
とても複雑で重要な処理に「// ○○しないと動かなかった・・・(´·ω·`)」みたいな感じで書かれていて少しイラっとした経験があります(笑)
「コメントに顔文字つける人なんているの？」と思われるかもしれませんが、ゲーム業界だとコメントに顔文字がついていることはそんなに珍しい事ではありません。

まとめ

以上が僕が普段心掛けているコメントのマイルールです。
「これらができればコメント運用は完璧！」とまでは言いませんが、コードの品質を一定以上保つためには有用なメソッドだと思います。
ぜひ参考にしてみてください。

もしかしたら将来AIが適切なコメントをつけてくれるようになって、今回紹介したメソッドのほとんどが無用なものになるかもしれません。
しかしそれはあくまでコードから判断できる範囲のコメントになるでしょうから、せいぜい適切度70%～80%くらいが限界だと思います。
それらのコメントを適切度100%にするのはエンジニアの仕事です。

コメント

タイトルとURLをコピーしました