良いコードコメントを書くためのガイド

• コードコメントの役割:

  • コードコメントは「自分が書いたコードが何をするか」を説明するだけでなく、設計上の決定事項やトレードオフなどの検討内容を文書化する
  • これにより、「コードの作成者が何をし、なぜそのようにしたのか」を説明できる
  • コードコメントは、過去のコーディング過程で下した判断の文脈を共有するのに役立つ
  • これはコードだけでは表現しにくい情報を伝える

• コードコメントの重要性:

  • 複雑なコードの前に付けられたインラインコメントは、後からそのコードを見る他の開発者の時間を節約する
  • プロジェクトが発展するほど、過去に下したコード上の判断の文脈を残すことが他の開発者の助けになる
  • コードが複雑なら、前に1行のインラインコメントだけでもあるべき
  • コードだけで、コード上の判断の文脈をはじめとするさまざまな情報を伝えるには限界がある

• 良いコードコメントの書き方:

  1. 簡潔に書く
     • 本当に必要なときだけ、必須の情報を含めてコメントを書く
       • やむを得ずコードが複雑なとき
       • 精度を高めるために詳細を追加するとき
       • 文脈が欠けているとき（例: 他のリポジトリやパッケージのコードを使うとき）
     • コメントで混乱や曖昧さを減らし、有用な文脈と情報を提供する
  2. TODO/FIXME コメントを使う
     • TODO/FIXME コメントは、「コードの特定部分の作業が完了していない、または修正が必要である」ことを示す方法
     • 関数の前に「TODO: XX機能を追加する必要があります」のように書く
     • コードを書いていて「この部分は後で見直す必要がある」または「この機能は今後開発しなければならない」と思ったとき、この方法を使えば関連事項を記録して追跡できる
     • 活用するとよい Extension: TODO Highlight
  3. コメントでコードを言い訳しない
     • 誤っていて不明瞭なコードにコメントを付けて言い訳するより、コードを書き直す
     • コメントで説明すべきコードもあるが、コメントに頼らず「コードそのもの」で語るべきコードもある
  4. AIを活用する
     • AIコメント生成ツールを使えば、特定の標準に従って一貫した形式でコメントを作成できる
     • プロジェクト全体でコメントの一貫性を保てるため、コードの可読性が向上する
     • 活用するとよいAIコメント生成ツール: Readable

[penza1]

コメントが必要に見えるなら、
コードのほうが間違っていないか考えてみるのはどうでしょうか。

コードと寿命や機能を共にしないコメントは、将来そのコメントを見る開発者や自分自身に混乱を与えてしまうことがあります。

過去の文脈が現在と無関係だったり、むしろ誤りの原因になっていたとしても、
その過去の文脈の文章のせいで現在の修正をためらったり、別の構造で解決しようとして回り道をしたり、
ミスをさらに誘発してしまうこともありますし……

経験上、当時は正しかったけれど今は間違っている理由まで分かるコメントは、そう多くないので……

[ironlung]

貴重なご意見を共有してくださり、ありがとうございます。いただいたご意見を考えてみると、コードの発展のためにも、コメントの必要性を丁寧に問い直す努力も必要だと感じました。 :)

[aqqnucs]

https://youtu.be/Bf7vDBBOBUA?si=0-v44x48-rlVsYCq

これを見ながら、コメントを過剰に書きすぎないようにも心がけています

[ironlung]

良い動画を共有してくださってありがとうございます！ :)

[iamchanii]

どれだけ道路がきれいに整備されていても、道しるべは必ず必要だと思います。だから最近は、コメントを書くことを習慣化しようと努力しています。

[ironlung]

インサイトをコメントで共有してくださり、ありがとうございます。いただいたお話を考えてみると、コメントも重要なテクニカルライティングの一種なので、ライティングの基本原則をあらためて振り返るきっかけになりますね。 :)

[balak]

コメントがなくても理解できるようにコードを書くのが一番だと思います

[ironlung]

はい、まずは基本に忠実であることが大切だと思います。コメントありがとうございます。 :)