コードの可読性を高める10大注釈技術を共有する。

本論文は、コードの可読性を高める10の注釈技法を述べている。皆さんに参考にしてあげます。具体的には以下の通りです。
多くのプログラマはコードを書く時、コードの可読性に注意しないで、他の人にコードを読む時にもっと多くの時間を使わせます。実際には、プログラマがコードを書く時に、コードに注釈を付けて、合理的なフォーマットでコードを注釈すれば、他の人にコードを確認しやすくなります。以下にコメントを付ける10のテクニックを共有します。
1.層ごとのコメント
コードブロックごとにコメントを追加し、各階層で同じ注釈方法とスタイルを使用する。たとえば:
各クラスに対して、要約情報、著者情報、最近の変更日付などが含まれます。
各方法に対しては、用途、機能、パラメータ、戻り値などが含まれる。
チームワークでは、標準化された注釈を採用することが重要です。もちろん、注釈仕様とツール（例えば、C〓のXML、JavaのJavadoc）を使用すると、注釈の作業がよりよく進みます。
2.セグメントコメントを使う
複数のコードブロックがあり、各コードブロックが単一のタスクを完了すると、各コードブロックの前に注釈を追加して、このコードの機能を読者に説明する。例は以下の通りです

// Check that all data records
// are correct
foreach (Record record in records)
{
  if (rec.checkStatus()==Status.OK)
  {
    . . .
  }
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

3.コード行の後にコメントを追加する
複数行のコードの各行にコメントを追加すると、各行のコードの後にその行のコメントが追加されます。これは分かりやすいです。たとえば:

const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F;  // mask bit TCP

コードとコメントを分けるときは、tabキーを使う開発者がいますが、他のいくつかはスペースキーを使います。しかし、タブキーは各エディタとIDEツールの間では表現が一致しないので、一番いい方法はやはりスペースキーを使います。
4.読者の知恵を侮辱しないでください。
これらの無駄なコメントを書くと、あなたの時間が無駄になり、コードの詳細についての読者の理解が移ります。

if (a == 5)   // if a equals 5
  counter = 0; // set the counter to zero

5.礼儀正しい
粗暴なコメントは避けてください。例えば、「注意してください。愚かなユーザーは負の数を入力します。」または「修復されたばかりの問題は最初の無能な開発者の手によるものです。」このような注釈はその作者の拙劣さを反映しています。誰がこれらの注釈を読むかは永遠に分かりません。
6.注目ポイント
あまり多く書かないでください。意味を変えて分かりにくい注釈が必要です。ASCIIの芸術を避けて、笑いを取って、詩情の画意、hyperverbosityの注釈。簡単に言えば、注釈を維持するのは簡単で直接的です。
7.同じコメントスタイルを使う
一部の人は注釈は非プログラミング者に理解される程度であるべきだと信じています。他の人は注釈は開発者に理解されればいいと思っています。いずれにしても、Success ful Strategies for Commenting Codeは注釈の一致性と対応する読者を規定し説明しました。個人的には、ほとんどのプログラマではない人がコードを読みに行きますので、コメントは他の開発者にとって必要です。
8.特有のラベルを使う
一つのチームで働く場合、他のプログラマとのコミュニケーションを容易にするためには、一致したラベルセットでコメントするべきです。例えば、多くのチームでTODOタグでコードセグメントを表現するには追加の作業が必要です。

int Estimate(int x, int y)
{
  // TODO: implement the calculations
  return 0;
}

注記ラベルはコードの解釈には使用しないでください。注意を喚起したり情報を伝達したりするだけです。この技術を使うなら、追跡して確認してください。
9.コードにコメントを追加する
コードを書く時にコメントを追加します。この時、あなたの頭の中には明確で完璧な考えがあります。コードの最後に同じ注釈を追加すると、あなたの倍の時間がかかります。「コメントを書く時間がない」「忙しいです」「プロジェクトが延期されました」とコメントしたくない言い訳をしています。一部の開発者はwrite comments before codeが心当たりを整理するために使うべきだと思います。たとえば:

public void ProcessOrder()
{
  // Make sure the products are available
  // Check that the customer is valid
  // Send the order to the store
  // Generate bill
}

10.自分のためにコードを注釈する
コードを注釈する時、将来あなたのコードを守る開発者だけではなく、あなた自身も見なければならないと考えます。Phil Haackマスターを使うと、「一行のコードが画面に表示されると、あなたもこのコードのメンテナになります」ということです。したがって、私たちがよく書いている注釈にとって、私たちは最初の受益者（被害者）になります。