Comments

Don’t comment bad code — rewrite it.
(Brian W. Kernighan and P. J. Plaugher)

• コメントは「必要悪」

  • 使わずにコードで表現できるに越したことはない

• コメントはコードで表現し損ねた(failure)ことを補うのが適切な用法

  • コメントは常に失敗(failure)。褒められたことではない
  • 使わなければならないときは、コードで表現できなかったことにしかめっ面をすべき
• なぜコメントに否定的なのか

• コメントはウソをつくから

  • 古いほど、説明対象のコードから遠いほど、間違っている可能性が上がる
• 不正確なコメントは、コメントが無いより悪い
• 真実はコードのみ

Comments Do Not Make Up for Bad Code

• めちゃくちゃなコードをコメントで埋め合わせるのに時間をかけるくらいなら、コードを綺麗にしろ

Explain Yourself in Code

• たいてい、コメントで言おうとしている名前の関数を切り出したほうがいい

Good Comments

• goodとはいえ、書かないに越したことはない

Legal Comments

• copyrightやauthorが社内コーディング規約で強制されることがある

• 契約や法的な資料を直接書くべきではない

  • 参照しよう

Informative Comments

• 「何に使うか」とか
• 関数名やクラス名に含めるに越したことはない

Explanation of Intent

• 設計上の決定などの背後にあった意図を伝える
• コードのアプローチには賛成しかねるが、何をしているかをひとまず書き留める

Clarification

assertTrue(a.compareTo(a) == 0); // a == a

• こういうやつ

• リスクとリターン表裏一体

  • コメントが正しいことの確認は難しい
  • 難しいからこそいちいち確認しなくていいようにコメントしている
• これもコード自身に説明させるに越したことはない
• 【補】上の例ならこうか

assertTrue(a.equals(a));

...

class WikiPagePath...
    public boolean function equals(WikiPagePath target)
    {
        return this.compareTo(target) == 0;
    }

Warning of Consequences

• 例

  • // このテストを有効化するとすごく時間がかかる
  • // 非スレッドセーフなので各インスタンス個別に生成しないといけない
• 前者はxUnitの機能を使うべき、後者はstaticなcreatorを封じるべき
• 改善の余地はあるにせよ、コメントの用法としては正当

TODO Comments

• まずいコードを放置する口実ではない

  • いつか直す・直してもらうもの
• 定期的にさらって可能なものはつぶそうね

Amplification

• 一見瑣末に見えるものが実は重要なとき、コメントで強調する

Javadocs in Public APIs

• これなくしてJavaプログラムを書くのは難しい

• 他のコメントよろしく、まずいコメントにならないよう注意を要する

  • ミスリーディング
  • 説明対象から遠い
  • ウソ

Bad Comments

Mumbling

• コメントの真意を汲み取るために他のモジュールを見ないといけない

  • 意図が伝わらない駄目コメント

Redundant Comments

• コード以上の情報がない
• コードを正当化するでもなく、意図や根拠を示すでもない
• 実装よりも読むのに時間がかかる
• コードよりも不正確なだけ

Misleading Comments

Mandated Comments

• 全メソッド・全変数にJavadocコメントを書くなど

  • コードがわかりにくくなる
  • 嘘コメントやミスリーディングなコメントの可能性を増してしまう

• 【所感】PHPのような、言語機構の不足をPHPDocコメントで補うようなケースではこの限りでないと思う

  • 嘘を見抜く静的解析も発達しているし

Journal Comments

• モジュール先頭に変更履歴コメントを記載する
• VCSがなかった時代かよ

Noise Comments

• 明らかなことの再記述

  • /** Default constructor. */ とか
  • 変数名の繰り返し
• 無視されるようになる
• 無視されるので更新されなくなる

Scary Noise

• Javadoc版ノイズコメント

Don’t Use a Comment When You Can Use a Function or a Variable

• 可能なら、コメントをそのまま局所変数(名詞)と関数呼び出し(動詞)に起こそう

Position Markers

// Actions //////////////////////////////////////

• こういうやつ

• 濫用NG

  • 滅多に使わないからこそ目立つ

  • 使いすぎると散らかるだけ

    • 無視される

Closing Brace Comments

• ネストが深いと欲しくなる
• ネストが深くなるのは関数が長い(たくさんのことをしている)から
• 関数を短くしよう

Attributions and Bylines

• 誰が・いつ変更したよ、というやつ
• VCS使え

Commented-Out Code

• やめろ

  • 他の人はおっかなくて消せない

    • 「何か重要だから残しているのだろう」
• VCS使え

HTML Comments

• JavadocコメントをHTMLや文字参照で書いてしまう
• 読みづらくなる
• コメントの抽出・装飾はツールの仕事であってプログラマの仕事ではない

Nonlocal Information

• 直近のコード以外を説明するな

  • 遠くのものを説明すると更新が漏れる

Too Much Information

• RFCの中身とかを直接コピーして持ち込むな

  • 参照せよ

Inobvious Connection

• コード自身では説明不足なのでコメントで補うのである
• コメント自体の説明が必要なのは残念なこと

Function Headers

• 良い名前の小さな関数には不要

Javadocs in Nonpublic Code

• ドキュメント自動生成対象外の内部関数にまでJavadocを書いてしまう

  • 邪魔で気が散る

英語

• frivolous

  • 分別のない、軽率な

• dogmatic

  • 教義上の

• crufty

  • お粗末な

    • S/W設計などが複雑すぎて

• pat oneself on the back

  • 得意になる、自画自賛する、自慢する

• grimace

  • しかめっ面をする

• be down on

  • …に恨みを抱いている

• bifurcate

  • 二股に分かれる

• blurb

  • 宣伝文、推薦文

• delude

  • 人をだます、欺く

• patently

  • 明らかに

• tome

  • 学術書

• flippant

  • 不真面目な

• poignant

  • 痛恨の、胸が痛む

• plea

  • 嘆願

• inconsequential

  • 取るに足りない

• mumbling

  • モグモグ言う

• recourse

  • 頼みにする

• entice

  • 気を引く、そそのかす

• in lieu of

  • に代わる

• blithely

  • 楽しく

• mandated

  • 強制された

• obfuscate

  • (複雑化させて)わかりにくくする

• vent

  • フラストレーション等を発散する

• attribution

  • 帰属

• bylines

  • 署名欄

• dreg

  • 飲み物のかす、おり

• imminent

  • 差し迫った

• anathema

  • 呪い、忌み嫌われるもの