コメントについて考えてみた

コメントについて
本気で考えてみた
やきに駆動 2.0
2012/10/27
@irof

とりあえず書き殴ってみた

コメント書いてます？

Question mark in Esbjerg by alexanderdrachmann

コメント書いてます？

なんで？
Question mark in Esbjerg by alexanderdrachmann

コメントを書く動機

コードがわかり辛い
実装の仕方がわからない
なんとなく
とりあえず

コメントを書く目的

コードの理解を助けるため
コードに書けないことを伝えるため

コメントは未来のために
Rosetta Stone by Spixey

コメントに書く内容

ドキュメントコメント
何が達成できるかを書く
コードを読まずに済ませる
コメント
意図や存在理由を書く
コードのメンテナンスを助ける

いいコードには
多くのコメントがある

いいコードには
多くのコメントがある
見苦しいコードには
多くのコメントが必要になる

いいコメント？

Question mark made of puzzle pieces by Horia Varlan

いいコメント？
正しい
明瞭である
情報を追加する
書かない


悪いコメント？


悪いコメント？
嘘・矛盾がある
大量にある
情報が増えない
悪いコードのゴマカシ


どうせ書くならいいものを

ウンコメントカタログ

設計書マッピング
https://gist.github.com/3292173

コメントで
ダメなコードを
取り繕うことはできない
悪いコードにコメント
をつけるな。
書き直せ。

素直に消す

履歴コメントとかは即座に消す。
全部バージョン管理ツールに任せて
しまいましょう。
……とは言え、残してるようなとこ
は無いですよね？ね？

まともな名前をつける

定数をマジックナンバーにしない
変数名に意味を込める
メソッド名で意図を表す
説明メッセージを使用する

メソッド・クラスの抽出

クラスやメソッドの抽出を行う。
抽出されたものの責務が明確になる
ので、きっとコメントは要らなくなる
に違いない。

対称性の原則に従う

同じメソッド内に登場する構文とかは
同じレベルのものであること。
対称性を意識するとコードの可読性
はかなり上がる。はず。

テストで表現する

コメントは変化に対応しなくても即座
にフィードバックをくれるわけじゃな
い。
コメントに複雑な条件などを書くくら
いならテストで表現する方法もなく
はない。
テストが十分に読みやすければ。

読む人を意識する

「誰でも読めるように」コメントを
書いてるとキリがありません。
コメントはコードに書かれるので、
プログラミングとシステムの概要は
理解していると考えていいはず。
コンテキストを意識することで、不
要なコメントは書かない。

コメントは消臭剤
そもそも臭くないところには
置かない
無臭じゃないので過剰に置く
と逆に臭い

コメントは装飾
悪いコードを覆い隠すことは
できない

Cakes later on... / Debs (ò‿ó)♪

コメントは純粋に良いものではあり
ません。
ボブおじさん曰く「必要悪」
コメントを書くのは、プログラミン
グ言語での自身の表現力が及んでい
ないことの現れです。
コメント書いたら負け。でも。

書くべき時は書くべし

おしまい。
肉が食べたいです
<参考文献>
* CleanCode
* CodeCraft
* 実装パターン
* 達人プログラマー
* プログラミング作法
* プログラマが知るべき
97のこと
* リファクタリング

Recommended