【まとめ】コードのコメントに対する自分の指針を決める

はじめに

今までコードの書き方の勉強には力を入れてきました。
ですが、コメントに対してはあまり意識せずにコーディングしてきました。

実際、コメントを書くのは面倒だし、書くことにメリットが見出せていませんでした。
理由は明確で、コメントを書くことのメリットや目的、自分の中での方針を決めるような時間を取っていなかったことが原因だと思います。

書く書かないなどいろんな流派があって答えはないと思いますが、
自分の中で理由とセットで意見を持つことは重要だと思うので、さっそくコメントにどう向きあうか考えてみます。

コメントを書くことのメリット・デメリット

まずはコメントを書くことのメリット・デメリットについて洗い出してみます。
こんな重要なメリットやデメリットもあるよ！！などありましたらコメント欄でご指摘いただけますと幸いです。

メリット

• コードを読まなくてもメソッドの使い方などがわかる
• 初めてコードを読む人でも理解が捗る
• 書いた人が当時困ったことなどを未来に残せる

デメリット

• コメントをちゃんと更新しないとコードと乖離したものになる
• コメント内容を間違って解釈し間違った使い方をしてしまう
• コメントを書くことで、時間がかかる
• 「コメントを書けばいいや」でコードが汚くなる

パッと思いつくメリット・デメリットを出してみました。
このメリット・デメリットからわかる事として、
コメントはコードを読む人（他の人、未来の自分）のためにあることがわかってきました。

どんな内容のコメントを書くと良いか

コメントを書く事の目的はメリットで分かったようにコードを読む人（他の人、未来の自分）のためにあるとします。
では、コードを読む人（他の人、未来の自分）のためにどんな内容のコメントを書くといいのか考えていきます。

Good

• コードでは伝えられないことをコメントに書く

  • 時間の都合や、スキル、状況によって微妙なロジックを書いたままコミットしてしまう事があると思います。
    そういったコードからは読み取れない背景をコメントで残すと読む人に情報を伝えられると思いました。

• メソッドだけでは処理内容が読み取れない時に、補足するようなコメントを書く

  • どんなにメソッドをわかりやすくしても伝わりにくいこともあるので、
    そういった時の補足説明としてコメントを残すと読む人が助かると思います。

• 抽象的なコメントを書く

  • 実装は具象なので、コードを読まなくても何をするメソッドやコードなのかを、
    イメージ出来るようなコメントを書くと、コードがより読みやすくなると思います。

Bad

• コードを見て直ぐにわかる内容は不要
  • だたメソッド名をコメントに書くなど、目的のないコメントはコードと重複するだけです。
    （私は結構書いてました。。。）

• コードと違う内容のコメントは不要

  • コードが必ず正ですが、間違ったコメントに惑わされる事があるかと思います。
    コードを修正したらコメントも修正する必要があるのはわかりますが、案外忘れがち・・・

• ボリュームの大きなコメントは不要

  • 1つのメソッドで、責務が大きいならメソッドを分割する事で、コメントも分割できると思います。（最大3行まで）
    また、文章だけで多くのことを説明するよりも、図の方がわかりやすい場合、ドキュメントに誘導するURLを貼ればいいかと思いました。（調べたところ、賛否両論なようですが、私は良いと思います。）

デメリットへの対策

上記のコメントを書くことのメリット・デメリットで挙がったデメリットへの対策を考えていきます。

• コメントをちゃんと更新しないとコードと乖離したものになる
• コメント内容を間違って解釈し間違った使い方をしてしまう
• コメントを書くことで、時間がかかる
• 「コメントを書けばいいや」でコードが汚くなる

• コメントは最後の見直しの時に書く

  • 書いてる途中で同時にコメントも書くと、メソッド化したり、内部の処理内容が追加したりして、
    最初に書いたコメント内容とコードが乖離していく可能性があります。なので最後に書くことで、コードとの乖離を防ぎます。
  • プルリク前までコメントを書かずに実装をすることで、コメントがなくても分かるようなコードを書く意識がつきます。
  • 上記によってシンプルなコードにはコメントをする必要が無くなります。
  • ※メソッドの中の処理の流れなどは最初に書くとコードが書きやすいのでおk。
  • また、先輩に聞いたところ、多くの人が先に書くと言ってました。

• 客観的にコメントを書くために1日寝かす

  • コードを書いてその日のうちにコメントを書くと、まだどんなコードを書いたか頭がしっかり覚えています。
    なので、可能なら次の日の朝など、フレッシュな客観視出来る状態でコメントを書くと、読み手の気持ちになってかけるかなーと思いました。

※ 時間がかかるのはしょうがない事なのかと思いました。
　コメントを書くことに時間を惜しんでも読む人の時間を膨大に使うだけなので

自分で自分にQA

自分の中で疑問に思ったことをQAの形で残しておきます。

• パブリックメソッドだけにコメントを書けば良いのか？

  • 優先度はパブリックメソッドの方が高いですが、プライベートメソッドにもコメントは必須だと思います。
    プライベートメソッドは外部から使われることはないですが、改修や調査をする際にプライベートメソッドも読まれます。
    自分で決めた方針が、コードを読む人のためなので、プライベートメソッドにもコメントを書くようにします。

• 英語か日本語どちらでコメントを書くか？

  • 英語派が多かったですが、日本語でいいかと思いました。
    理由としては日本人エンジニア全員が英語を出来る訳ではないので、それならば大多数が読める日本語で書いた方がミスリーディングなどが防げると思いました。実際ライブラリのコメント読むときも英語でびっしり書かれてるとやる気が失せるし

• 文字では分かりづらい場合は？

  • 上述しましたが、URLなどでドキュメントに誘導することはありだと思います。
    数式などがコメントに大量に書かれていても読む気が失せますし、なんでその式になったのか背景もわからないので、
    読む時に大変になるからです。

• 処理の流れにもコメントを書くか？

  • 書く。
    最初は不要かと思いましたが、実際にコメントを書いた場合、書いてない場合で、書いてある方が流れをイメージして読むことができました。

最後に

一旦自分の中で、コメントに対する方針が決まったので、今後はちゃんと目的意識を持って取り組めそうです。

若手の時期にこういった事を考えるきっかけを下さった先輩方には感謝しかないですね。。。
もっとこんな事を意識すると良いなどご意見待ってます！！