概要
- コメント は「なぜ」だけでなく「何を」も説明すべきという主張
- クリーンコード とコメントの役割の違いを解説
- コンテキストスイッチ の弊害を指摘
- メソッド分割 とコメントのバランスを議論
- コメントの「何を」説明する有用性を具体例で提示
コメントは「なぜ」だけでなく「何を」も説明すべき理由
- 一般的に「 コメントはなぜを書くべき、何を書くべきではない」とされる風潮
- しかし、 コードだけで全てを明確にするのは困難 な場合も存在
- 例:
- //weight, radius, price w = 10, r = 9, p = 1 よりも weight = 10, radius = 9, price = 3 の方が明確
- 省略名（w, r, p）は直後なら意味が分かるが、 後で見たときに混乱 しやすい
- 例: 「w」を「width」と誤解するリスク
- コメントはクリーンコードの代用にならない が、補助的な役割として有効
「なぜ」をコメントで説明する重要性
- 「なぜ」は コミットメッセージやテストに残すべき という意見もある
- 例:
// Clear twice to deal with bug ABC in library XYZ, see [link]
XYZ.clear();
XYZ.clear();
- このコメントがなければ、「なぜ2回呼ぶのか」理解できず誤った修正をする恐れ
- コミット履歴を遡るのは手間 であり、コンテキストスイッチが発生
- コメントで直接理由を記載することで 即座に意図を理解 できる
説明的なコードが逆に理解を妨げる場合
-
Bob Martinの「Extract Till You Drop」例
-
説明的なメソッド分割により コードが短く見える が、全体理解には 複数メソッドの追跡が必要
-
バグ修正時など、 何度もメソッド間を移動する手間 が発生
-
コメントで「何を」説明することで 一箇所で理解できる 利点
- 例: Pattern symbolPattern = Pattern.compile("\$([a-zA-Z]\w*)"); // 例: $F1a3 Matcher symbolMatcher = symbolPattern.matcher(stringToReplace); // 全シンボルを置換 while (symbolMatcher.find()) { ... } // ここで全インスタンスを置換
「何を」説明するコメントの有用性
- 全てのケースでコメントが必要なわけではない
- しかし、 一部のケースでは「何を」説明するコメントが最適解
- コメントを全否定せず、 状況に応じて柔軟に活用 する姿勢の重要性
Uncle Bob批判と賛同するエッセイ紹介
- Uncle Bobの例をよく批判しているが、「The Lurn」というエッセイには賛同
- プログラミング言語学習の過剰評価 よりも、他の有用な知識の重視を提案
- 結論: コメントは「なぜ」だけでなく「何を」も適切に説明することで、 コードの可読性と保守性を向上 させる
- クリーンコード と コメント のバランスを意識した開発姿勢が重要