コメントは1つで十分

ディフェンシブRプログラミング

Colin Gillespie

Jumping Rivers

私の場合は…

  • いまは明らかなコードでも
  • 数週間後には明らかでなくなることが多い
ディフェンシブRプログラミング

コメント

  • R のコードには # でコメントを追加できます
  • ただし、よいコメントを書くのは意外と難しい！
# これはコメント
# 上のコメントはあまり有益ではない
# それとも有益？
ディフェンシブRプログラミング

ヒント1: 明白なコメントは避ける

  • 何が「明らか」かは判断が難しいことがあります
    • たとえば次のコメント
       # データセットをループ
 for (dataset in datasets) {
  # データセットを読み込む
  r <- read.csv(dataset)
 }
      は一見妥当です
    • しかし、やや当たり前すぎるかもしれません
ディフェンシブRプログラミング

ヒント2: 更新しないコメントは避ける

最もよくあるのは、ファイル先頭のヘッダーコメントです

# 最終更新: 1967-02-25
# 作成者: D Law
# ステータス: No 1
  • こうしたコメントはほとんど更新されません
  • かつて # 使用パッケージ一覧: XXX, YYY を見かけました
ディフェンシブRプログラミング

ヒント3: 一貫性を保つ

  • 常に単一の # または二重の ## で始める
  • 先頭は大文字で—文法規則に従う
  • 冗談には注意
    • 自分は面白くても、他人は不快に感じることがあります
  • 「間違って見える」コードには必ずコメントする
  • 今後の課題には # TODO や # XXX を使う
ディフェンシブRプログラミング

演習に進みましょう

ディフェンシブRプログラミング

Preparing Video For Download...