コメント

コメントはプログラムの実行時は無視される文字列です。

行頭からでも、行の途中からでも#からはじまり、その行の最後までがコメントです。

# ここはコメントです。
# ここもコメントです。
print('Hello')
# print('World')  この行もコメントです。
a = b + c # 行の途中からのコメントです。

コメントを書く時

  • 実装上注意が必要な難解な部分
  • TODO
    • まだ実装していないが、必要な事項
    • コメントの最初をTODOからはじめます(例: # TODO(Suzuki): 問題があるが保留中)
  • プログラムを改修したときの背景・経緯
  • 動作させたくないコードをコメントする(コメントアウトと表現されます)。

コメントの悪い利用方法

実装自体の説明(コードを見ればわかる)

# 合計が300より大きい場合の処理
if sum > 300:
    print('Big')
  • 終わったTODOが残っている。
  • 実装と関係ない愚痴が書いてある。
# この書き方どうかと思います(コメントに書かずにコードレビューで指摘してあげてください。)
# このテストって意味あるんですかね(コメントに書かずに担当者と話し合いましょう)
# 何で俺が修正しないといけないだよ(嫌ならコメントに書かずに上司に相談しましょう。)
# 今まで見た中で一番ひどいコメントはプログラムの改修をしようとコードを開いたら、
# クリスマスに徹夜で作業している担当者の愚痴が100行にわたってコードに埋め込まれていたものです。
# ソースコードは他の担当者やお客様が見る可能性があります。
# 情報として意味のないことを書くのは止めましょう。
  • 修正前のコードをコメントアウトして、修正後のコードを書く(Git, Subversionなどの履歴管理ツールを利用しましょう)