「クリーンコードは散文のように記述する必要があります」 - ロバート・C・マーティン
一般的な問題は、不正なコードのコメントがたくさんあるということです。これは、最も目に見える徴候の乱雑なソースコードです。
各プログラマの目標は、コードのコメントを防ぐために、清潔で表情豊かなコードを記述する必要があります。変数の各目的関数などはその名前と構造に暗示されなければなりません。
他の人があなたのコードを読んだとき、彼らはあなたのコードが何をしているか確認するために、コメントを読んではいけません。名前付きの良いクラスと関数は、よく書かれたフィクションのように、あなたのコードを介してリーダを導く必要があります。読者が新しいカテゴリや機能を見たとき、彼らはそれに見るかを理解するのは難しい混同してはなりません。
作業時間が非常に少数の開発者がコードを書くのに費やされている、覚えておいてくださいコードを読んで過ごす時間など多くのコードを理解。
自分の失敗をカバーするために注意
私は頻繁に実行する変数または関数名上記のコードを記述するコメント（又は行うべき操作）コンテンツを参照します。これらのコメントは、感情がかつて眉、このコードは名前が表情豊かな想像する方法があることがある、またはその機能はただ一つのことではない私を与えました。
コードで指定されたことは非常に重要です。他の開発者があなたのコードを理解できるように、あなたは、正確かつ精密に命名コードのすべての部分のエネルギーの多くを費やす必要があります。
// 按状态查找员工
List<Employee> find(Status status) {
...
}
复制代码この例では、検索の名前が記述されていない、この関数の作者は、機能を説明説明コメント機能を残しておく必要があります。私たちは別のモジュールから呼び出された検索機能が表示されたら、その役割は謎です。それが見つかりましたか？それは何を意味するのでしょうか？それはそれ見つけたものに戻りましたか？それはどのように見つけたものを見つけるには？コメントを書くために必要がある場合は言った彼の著書「クリーンコード」でボブ叔父さんのように、あなたはコードによって彼らの真の意図を表現することはできません。
私たちは、その役割を理解するためには、上記のコメントのそれぞれの機能をチェックする必要はありません。
List<Employee> getEmployeesByStatus(Status status) {
...
}
复制代码今、明らかにコメントが不要になり、この機能の具体的な役割、ことがわかります。それは私が失敗した次のコメントへの方法を考えることができます。
冗長コメント
これらは完全に不必要な、あなたのコードを混乱します。これらのコメントの形成にあると読者を案内します冗長コメントの数を追加し、「退屈」の考え方は、すべてのコメントをスキップし、重要な注意事項があるのでとき、読まれることはありません。
//此函数发送电子邮件
void sendEmail() {
...
}
//此函数发送电子邮件
public class Employee {
...
}
/ **
* @param title CD的标题
* @param作者CD的作者
* @param track CD上的曲目数
* /
public void addCd(String title, String author, int tracks) {
...
}
复制代码ほとんどの場合、強制的な冗長性があります。多くの企業は、各カテゴリで、これを必要とします。あなたの上司がそうするように求められた場合は、EMMあなたはないにそれらを求めることを試みることができます。
抽象化の間違ったレベル
あなたは、コードの一部は、何かをする必要が長い記録機能またはこれを持っている場合は、これらの規則に違反することがあります。
- この関数は一つのことを行う必要があります。
- 機能は最小限でなければなりません。
これは一例です
//此函数计算价格，与销售额进行比较
//促销，检查价格是否有效，然后
//向用户发送促销电子邮件
public void doSomeThings（）{
//计算价格
...
...
...
//将计算出的价格与促销活动进
...
...
...
//检查计算的价格是否有效
...
...
...
//向用户发送促销信息
...
...
...
}
复制代码あなたが成功し、単一の論理機能への各部分をカプセル化すると、コードが説明するようにその効果を発揮します画像を注釈を付けする必要はありません。
次のように再構築：
public void sendPromotionEmailToUsers（）{
calculatePrices（）;
compareCalculatedPricesWithSalesPromotions（）;
checkIfCalculatedPricesAreValid（）;
sendPromotionEmail（）;
}
复制代码メモ代わりのコードの各部分は、各論理ブロックは、それ自体の機能にカプセル化されるべきです。
まず、それが改善可読性を。各コードブロック行ずつ読み込む必要はありません。私たちは、単に補助機能名を読み、その役割を理解することができます。私たちは、各関数内の詳細を知りたい場合は、実装を見ることができます。
第二に、それは増加テスト容易性を。上記の例では、各ユニットテストのために別々に機能することができます。パッケージは、機能を分離しない場合、各部分のより大きな機能sendPromotionEmailToUsers（）をテストすることは困難です。テストへの困難な複数の機能を実行するための機能。
最後に、それは増加の再構成を。彼らの論理機能へのパッケージの各部分では、将来の変化を維持しやすく、かつ個々の関数の機能は、機能だけの動作を変更するために隔離されています。私たちは、関数のローカル変数は、関数の長さにわたって存続使用する場合は、密結合の機能以来、それは場合には困難であることは他の場所で再構成関数の変更にはなりません。
コメントコード
ロードキルとして見られるべきコードをコメントアウトしてください。それを見てはいけない、それはニュースではない、それはちょうどそれを取り除く、どこから来るか、質問しません。もはやそれはコードのにおいを残り時間が長くなり、残って......
/ *
public void oldFunction（）{
noOneRemembersWhyIAmHere（）;
tryToUnCommentMe（）;
iWillProbablyCauseABuildFailure（）;
HAHAHA（）;
}
* /
复制代码あなたは他の人が恐れているの削除削除削除しませんが。あなたは後でそれが必要な場合は、右、VCSを使用する必要があるため、あなたは常に、バージョン管理システムを確認することができますか？（そうでない場合は、私が行ったとき）
TODOコメント
TODOコメントを記述しない、とだけ......それをしないのですか？時間のほとんどは、これらのノートは忘れられるだろう、と後で無関係か間違っていることがあります。別のプログラマが後でTODOのコメントを参照してください場合は、それらがどのように必要かどうかを知っていますか？
あなたが別の合併チームメイト（通常は長期のための）を待っている場合でも、時折TODOコメントが良いです。あなたはそれを修正して提出することができるまでは、行うことができます。
「あなたがレビューを書いて必要性を感じるとき、私たちは最初のコメントは不要になってきたようにコードをリファクタリングしてみなければなりません。」 - Martin Fowler氏
嘘ノート
ジミーは、コメントの上にマークされ、彼の新しい機能で書いたとき、彼は彼が彼のコードを見て、将来の開発に貢献したと思いました。実際には、彼が本当にやっていたことはトラップを設定しました。彼のコメントは、単に厄介なトラップになるのを待って、触れられることなく、数ヶ月または数年のために休眠大きな嘘（しゃれ意図）であってもよいです。そしてある日、復興の何百もの一つと需要のリモートモジュールの数から彼のコメントの変化は、間違ったブートディスクアクセス無数の夏にはまだ失敗、しかし。
あなたは1行のコードを変更すると、あなたがコードを知っていますかどのようにコメントの残りの部分に変更を加えることはできません有効ではありませんか？知る方法はありません。コメントは破壊されなければなりません
public class User {
...
//它包含用户的名字和姓氏
String name;
...
}
复制代码その後、変更の需要が、彼らは、姓と名に名前を分割したいです。
public class User {
...
// 它包含用户的名字和姓氏
String firstName;
String lastName;
...
}
复制代码今間違ったコメント。あなたは、変更を反映するために、コメントを更新することができますが、実際に手動で変更するたびにすべてのコメントを維持したい場合は？あなたは、開発者ではなく、ドキュメントです。
しかし、コメントは簡単に気づくことができ、問題を変更する必要はありません。しかし、それはまた、このパラメータ名は、ユーザーの姓と名でコメントします、そのプログラムのどこかで保証することは難しいです。コードの変更の小片を置き、あなたはコードのコメントの多くは無効であることがあります。
別の例を見てみましょう：
//根据状态处理员工
void processEmployees（）{
...
List < Employee > employees = findEmployees（statusList）;
...
}
//这会按状态列表查找Employees
List < Employee > findEmployees（List < String > statusList）{
...
}
复制代码そして、誰かが名前で一覧表示ではなく、状態の従業員のリストを見つけるために、関数findEmployeesを変更するように頼まれました。
//根据状态处理员工
void processEmployees（）{
...
List < Employee > employees = findEmployees（statusList）;
...
}
//这会按状态列表查找Employees
List < Employee > findEmployees（List < String > nameList）{
...
}
复制代码まず、上記のコメントのfindEmployeesは失敗しているので、変更する必要があります。問題ありませんよね？間違いました。
コメント上記processEmployeesも失敗し、そのために変更する必要があります。どのように他の多くのコメントがこの小さな改造を無効に変更されましたか？この変更は、ソースコードの嘘でコメントの数を作成しますか？
別の方法：
void processEmployees（）{
...
List < Employee > employees = findEmployeesByName（nameList）;
...
}
List < Employee > findEmployeesByName（List < Name > nameList）{
...
}
复制代码あなたが正確であり、正確にあなたの関数に名前を付ける場合は、コメントを必要としない、とあなたは、コード内で嘘を広めることはありません。
「コードは嘘はありません、コメントがある。」 - ロン・ジェフリーズ
やるときは、Notesそれを必要とします
私は多くの開発者がコードのコメントの筋金入りの支持者を知っている、彼らのために、私は時々コメントが可能であることを認めなければなりません。しかし、あなたが書く各パラグラフは、正当な理由を持っている必要があります
複雑な式
あなたは、複雑なSQL文や正規表現を使用している場合は、コメントを書くことを続けてください。きれいにコードに難しいことのようなステートメントを表現します。上記のコメントを追加するには、これらの式では、より良いあなたのコードを理解するために、他の開発者を支援することができます。
// 格式匹配kk：mm：ss EEE，MMM dd，yyy
Pattern timePattern = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w*, \\d*, \\d*");
复制代码ご注意警告
あなたは、このコードのバグを発生することがあり、他の開発者に警告する必要がある場合は、このコードの近傍にコメントを残すことができます。これらのコメントは、行動の神秘的なオーラのコードとして機能し、あなたのコードに値を追加することがあります。
意図を明確化
あなたが本当に無駄という名前の場合、それはあなたの失敗を負担して、コメントを記述する必要があります。あなたは、コードを記述するための責任があるので、これまでの滞在のために悪い書かれたコードを入れないでください。
コメントを書くことがある場合は、それがローカルであることを確認してください。失敗と嘘になる運命にその非ローカル参照から離れてのコメント。関数を参照または変数のコメントは、直接その上に配置する必要があります。Cautionメモは、それが参照するコードの上または横になることがあります。あなたのIDEがハイライト表示され、コメントをサポートしている場合は、あなたのコメントは警告コードの残りの部分から目立つようしてください。
遂に
私は、コードのコメントの気持ちを作成しました。私はそれらを軽蔑しますが、私は時々、彼らが必要とされていることを知っています。
だから、非常に多くのコメントを書くことはおやめください。
本論文では、それが共有するために作られた翻訳後修飾となるように深く、ツイッター上の大きな外国の神ブライアン・ノーランドの議論を参照することです。私は自分のコードがエレガント散文のようなことができることを願っています。
どのようにあなたのコードのコメントを書くことではない
、「私は申し訳ありませんが、私のコードは、コメントを書かれていません」（エスケープ