ソース管理を使用していないいくつかの場所で働いています。彼らは、変更を説明したコードの周りにコメントを入れるという習慣に乗っているように見えました。ファイル内の変更履歴
これは、コードを読みにくくすることが判明しました。改訂履歴でチケットを変更に合わせることができるように、ソース管理を導入した後にそのようなコメントが不要であることはかなり確信しています。
しかし、私は確信が持てません。ファイル内のファイルとコミットメッセージのメジャーリビジョンを文書化するとよいかもしれません。これは、コードをより読みやすくするはずです。コードの変更を文書化するベストプラクティスの方法はありますか。あまりに複雑すぎるのではなく、それを読もうとしている人にはまだ説明が残っていますか？
ファイルの先頭の変更点のリスト（他のすべての引数です）ではなく、コード内のコメントについて説明しています。
コードにあるドキュメントには、近くにあるコードを記述する必要があります。コードが変更された場合は、文書もそれに応じて変更する必要があります。バージョン管理システムは、変更された内容と変更された理由を管理する必要があります。コードとそのドキュメントを仕事にする（物事をやって、そのやり方とその理由を記述する）、そしてバージョン管理システムに任せて（バージョンと変更を制御/文書化する）。
現在の（現在のコード）の履歴を表示するたびに、問題が発生することを要求しています。それはいくつかの変更があった場合、コードの特に変化の重い領域がどのように見えるかを考えてみてください！
ほとんどのソース管理システムには、 "Annotate"または "blame"コマンドがあります。各リビジョンでどのコードが変更されたかを示します。
この情報はプログラムの動作を変更したり、プログラムを理解しやすくするものではないため、プログラムには含まれません。
私は、誰が変更されたのか、どのラインがどのラインに変更されたのかを示すだけであることを理解しています。これは、多くのリビジョンを持つ可能性のある古いコードでは役に立ちません。 –
大きな変更やリファクタリングをコード内のコメントとして記録するとよいでしょう。多量のコメントを読むのは面倒ですが、コメントを無視してコードを読むだけで十分だと思います。何かを混乱させたり、何かを変えようと誘惑したり、近くにコメントがある場合は、以前のバージョンのdiffを使って、何が変わったのか、なぜそれを知るのか、コメントを読む傾向が強くなります。
コード内でのコメントの変更は、説明的な方法で可能ではないと思わないでください。
しかし、私は「ファイルの変更履歴」について言いたいと思います。私はこれがまったく役に立たないと思う。比較するファイルのバージョンを知りたい場合を除き、「NNNN」タスクで導入された相違点を確認してください。ファイルの先頭には、 "NNNN date - small description"という行があります。そして、私たちのソース管理者は、このラインが誰にどのバージョンで導入されたかを "言う"ことができます。
この行がなければ、正しいバージョンを見つけるためにすべてのバージョンを調べます。
コメントが時間に影響されていない場合、それは悪い考えです。代わりに、バージョン管理システムのソースファイルにコメントを付けてください。
私は仕事中常にこの問題を見ています。私が現在取り組んでいるコードベースは、1979年にさかのぼります。あなたはその時間をかけて築き上げてきた以下のようなコメントと難しさを想像することができます：
「下の行には、バグXYZを解決するようで、予期せぬ問題が発生した場合に戻ります」私はそれが非常にわかりやすいではありません実現
を最初のところでコメントしていますが、svn/cvs/etcのそのようなものです。実際にはとても便利です。コードのようなコメントは、疑念の種をまきます。コメントは削除できますか？私がこのコメントに関連するコードを振り返らなければならない不本意な問題はありますか？
コードベースの各メソッドには独自の変更履歴があります。メソッドのコードが変更されると、そのヘッダは新しいエントリを取得します。コード自体はヒストリコメントで混乱することはなく、メソッドヘッダのみが混乱します。各変更履歴項目は、一般的な意味でのコード変更の理由を簡単に説明する1行または2行で構成されています。変更文書には、バグレポート、開発プロジェクト、設計文書などへのリンクも含まれています。
このようなエントリは、多くの場合、コードはそのままです。バグを修正するためにそこにいる場合、ヒストリトレースはいつもバグを導入したコードの変更、変更が何をしようとしているのか、そして修正を決定する際に他に何を知っておく必要があるのかを常に伝えます。
OTOH - ノイズの場合には、コードの内容に記述され、誰が変更したかについてのコメントの詰まり。
私は今使っているプログラムがそれを理解するのに役立っていることを知っているのだろうか？あなたは読みやすさを助けると言います。どうやって？
古い方法がうまくいかず、新しい方法が直感的ではないために何かが変更されたときは、いつも知っておく必要があるため、コードでコメントする必要があると思います。もう一度やってはいけません。それはもっと理にかなっているように見えますが、それでもやってはいけません。そうでなければ、私はそれが助けられるとは思わない。
これに答えるために刺すようになります。
ソースが変更されるたびに文書を読み込むことは困難ですが、特に直観に反するコードがあり、特定のチケットのために導入された場合、そのコードがなぜ奇妙なのかをメモしてください。
しかし、コードはまだ文書化する必要があります。あなたはあなたが
/* make headers blink */
に置きたいと思うかもしれ
/* ticket 101: add blink tag to headers, JF - 20010102 */
に入れない作りながら、人々がコメントの前者のタイプをやめたときにかなり頻繁に、彼らは彼らのコメントに大規模な削減と、これは悪いですので、 。
私は考える必要はない、私はそれを見て、それは恐ろしいです –