コーディング技法にはソフトウェア開発のさまざまな要素が含まれます。コーディング技法は、通常、アプリケーションの機能に影響を与えることはありませんが、理解しやすいソース コードを記述する上で重要な役割を果たします。ここでは、プログラミング言語、スクリプト言語、マークアップ言語、およびクエリ言語を含む、あらゆる形式のソース コードについて考えます。

ここで定義するコーディング技法は、柔軟性のないコーディング規則ではありません。ソフトウェア プロジェクトでコーディング規則を策定するためのガイドとして役立ててください。

コーディング技法は、次の 3 つのセクションに分かれています。

• 名前
• コメント
• 書式

名前

名前付けスキームは、アプリケーションの論理の流れを理解するために、有力な手掛かりとなります。名前は "どのように" よりも "どのようなものか" を示すようにします。基になっている実装は変更されることがあるため、それを示すような名前は避けます。これによって、抽象的な層を維持でき、複雑さが解消されます。たとえば、GetNextArrayElement() ではなく、GetNextStudent() を使用します。

適切な名前付けが困難なときは、その項目の用途をさらに分析したり定義したりする必要があります。名前の意味は十分に伝わり、冗長でない程度の長さにします。プログラムを作成する上で、項目に一意の名前を付ける目的は、別の項目と区別することだけです。わかりやすい名前は、それを読む人にとって手掛かりとなります。したがって、人が理解しやすいような名前を付けることが必要です。ただし、選択した名前が、使用する言語の規則や標準に適合していることを確認してください。

推奨される名前付け技法を次に示します。

ルーチン

• 主観的に解釈されやすい、捉えどころのない名前は避けます。たとえば、ルーチン名 AnalyzeThis() や、変数名 xxK8 などは使用しません。このような名前は、抽象性を保つというよりも、あいまいさを増す名前です。
• オブジェクト指向言語の場合、クラス プロパティの名前にクラス名を含めると冗長になります。たとえば、Book.BookTitle などは避けます。代わりに、Book.Title とします。
• 特定のオブジェクトに対してなんらかの操作を実行するルーチンには、動詞-名詞方式の名前付けを使用します。たとえば、CalculateInvoiceTotal() とします。
• 関数のオーバーロードが許されている言語では、すべてのオーバーロードが類似の関数を実行することになります。関数をオーバーロードできない言語では、類似の関数どうしを関連付ける名前付け規則を定めます。

変数

• 変数名の末尾に計算修飾子 (Avg、Sum、Min、Max、Index) を追加します。ただし、それが適切な場合に限ります。
• 変数名には、対称的なペアを使用します。たとえば、min/max、begin/end、open/close などがあります。
• 複数の単語を連ねた形式の名前が多いため、読みやすいように大文字と小文字を組み合わせて使用します。さらに、変数とルーチンを区別しやすいように、ルーチン名には Pascal 形式の組み合わせ (CalculateInvoiceTotal) を使用します。この形式では、各単語の先頭を大文字にします。変数名には、Camel 形式の組み合わせ (documentFormatType) を使用します。この形式では、最初の単語を除く各単語の先頭を大文字にします。
• ブール型の変数名には、Yes/No または True/False の値を導く Is を含めます。たとえば、fileIsFound とします。
• ステータス変数の名前に Flag などの用語を使用することは避けます。ステータス変数は、3 種類以上の値を取り得るという点で、ブール型の変数とは異なります。たとえば、documentFlag ではなく、内容を詳しく示す名前 documentFormatType とします。
• 数行のコードにしか出現しない生存期間の短い変数にも、意味のある名前を使用します。i や j など、1 文字だけの変数名は、短いループのインデックスとしてだけ使用します。
• リテラルの数値や文字列は使用しないようにします。たとえば、For i = 1 To 7 などは使用しません。代わりに、名前付き定数を使用して、簡単に保守および理解できるようにします。たとえば、For i = 1 To NUM_DAYS_IN_WEEK とします。

テーブル

• テーブルに名前を付けるときは、単数形の名前にします。たとえば、Employees ではなく Employee とします。
• テーブルの列に名前を付けるときは、テーブル名を繰り返さないようにします。たとえば、Employee というテーブル内のフィールドに、EmployeeLastName という名前を使用することは避けます。
• 列の名前にデータ型を含めないようにします。これによって、後でデータ型の変更が必要になったときの作業量を削減できます。

Microsoft SQL Server

• ストアド プロシージャに sp というプリフィックスを使用しないでください。このプリフィックスは、システムのストアド プロシージャの識別用に予約されています。
• ユーザー定義の関数に fn_ というプリフィックスを使用しないでください。このプリフィックスは、組み込み関数の識別用に予約されています。
• 拡張ストアド プロシージャに xp_ というプリフィックスを使用しないでください。このプリフィックスは、システムの拡張ストアド プロシージャの識別用に予約されています。

その他

• 省略形の使用は最小限に抑えます。ただし、既に一貫して作成されている省略形は使用できます。省略形の意味は 1 つに限ります。同様に、各単語の省略形は 1 種類に限ります。たとえば、minimum の省略形として min を使用する場合は、常にその省略形に統一します。また、min を minute の省略形としても使用することは避けます。
• 関数に名前を付けるときは、戻り値に関する説明も含めます。たとえば、GetCurrentWindowName() とします。
• ファイル名やフォルダ名は、プロシージャ名と同様に、その用途を正確に表す名前にします。
• 異なる要素に同じ名前を再利用することは避けます。たとえば、ルーチン名を ProcessSales() とし、変数名を iProcessSales とすることは避けます。
• 要素の名前に、write と right などの同音異義語を使用することは避けます。これによって、コード レビュー時の混乱を防ぐことができます。
• 要素の名前に、スペルを間違いやすい単語を使用することは避けます。地域によるスペルの違いにも注意してください。たとえば、color と colour、check と cheque などの違いに注意します。
• データ型の識別に記号を使用することは避けます。たとえば、文字列を表す $、整数を表す % などは使用しません。

コメント

ソフトウェアのドキュメントには、外部ドキュメントと内部ドキュメントの 2 つの形式があります。仕様書、ヘルプ ファイル、デザイン ドキュメントなどの外部ドキュメントは、ソース コードの外で管理されます。内部ドキュメントは、開発者が開発時にソース コードに書き込むコメントから成ります。

外部ドキュメントが存在する場合でも、ハード コピーのドキュメントは誤って配置される可能性があるため、ソース コード一覧は独立して存在する必要があります。外部ドキュメントは、仕様書、デザイン ドキュメント、変更要求、バグ履歴、および使用されるコーディング規則で構成されます。

ソフトウェアの内部ドキュメントでは、ソース コードと並行してコメントを確実に保守および更新することが課題の 1 つです。ソース コードに適切にコメントを加えても、実行時には役立ちません。しかし、特に複雑で厄介なソフトウェアを保守する開発者にとっては、コメントが計り知れないほど貴重な要素になります。

推奨されるコメント付け技法を次に示します。

• C# で開発を行っている場合は、XML ドキュメント機能を使用します。詳細については、「XML ドキュメント」を参照してください。
• コードを変更する場合は、その周囲のコメントも必ず最新の状態に更新します。
• 各ルーチンの冒頭に、そのルーチンの用途、前提条件、制限事項などを示す、標準の再利用可能なコメントを加えておくと役立ちます。再利用可能なコメントは、ルーチンの存在理由と機能を簡潔に説明する文にします。
• コードの行末にコメントを追加することは避けます。行末にコメントがあると、コードが読みにくくなります。ただし、変数宣言に注釈を付ける場合は、行末にコメントを付けます。この場合は、行末のコメントをすべて共通のタブ ストップに揃えます。
• アスタリスク (*) で 1 行全体を埋めるような、無駄なコメントは避けます。代わりに、コメントとコードの間は空白で区切ります。
• 記号を使った枠でコメントのブロックを囲むことは避けます。見栄えはしますが、保守が困難です。
• 配置の前に、一時的なコメントや無関係なコメントをすべて削除します。これによって、将来保守作業を行うときの混乱を回避できます。
• コードの複雑な部分を説明するためにコメントを加える必要がある場合は、コードの書き直しが必要かどうかを調べます。少しでも書き直しが可能な場合は、不良なコードを使用しないように書き直してください。通常は、人間の作業効率のためにパフォーマンスを犠牲にしてコードを簡素化することはしません。しかし、パフォーマンスと保守性のバランスを保つことが必要です。
• コメントを書くときは完全な文章にします。コメントはコードを明確にするものです。逆にあいまいさをもたらすようなコメントは避けてください。
• 後で時間を取ることは難しいため、コーディングと並行してコメントを加えます。また、作成したコードを後日見直す機会を設けます。今は明白に思えることも、6 週間後には明白でなくなる場合があります。
• ユーモアを込めた補足解説など、余分なコメントや不適切なコメントは避けます。
• コメントは、コードの意図を説明するために使用します。コード行を逐一翻訳するようなコメントは避けます。
• コード内で簡単に解釈できない部分には、すべてコメントを加えます。
• 特にチームで開発を行う場合は、問題を繰り返さないため、バグ修正や問題回避コードに必ずコメントを加えます。
• ループや論理分岐から成るコードには、コメントを使用します。ソース コードを読むときの重要な手掛かりとなります。
• アプリケーション全体を通じて、デリミタと構造が統一された、一様なスタイルでコメントを作成します。
• コメントとコメント デリミタの間は、空白で区切ります。これによって、コメントが明白になり、色分け表示がなくても位置を簡単に判別できます。

書式

書式を整えることによって、コードの論理構成が明瞭になります。ソース コードを一貫した論理的な書式で作成しておくと、作成者だけでなく、ソース コードを解読するほかの開発者にも役立ちます。

推奨される書式化技法を次に示します。

• インデントの標準サイズを空白 4 個などに定め、それを一貫して使用します。所定のインデントを使用して、コードの各部を揃えます。
• ソース コードのハード コピーを作成するときは、Monotype フォントを使用します。
• 対を成す左中かっこと右中かっこを垂直に揃えます。次に例を示します。
  for (i = 0; i < 100; i++)
  {
     ...
  }

  傾斜スタイルも使用できます。この場合、左中かっこは行末に、右中かっこは行頭に置きます。次に例を示します。

  for (i = 0; i < 100; i++){
     ...
  }

  どちらのスタイルを選ぶ場合でも、ソース コード全体を通じてそのスタイルを使用します。

• 論理構造に従ってコード行にインデントを設定します。インデントを設定しないと、コードの論理を追うことが困難になります。次に例を示します。
  If ... Then
  If ... Then
  ...
  Else
  End If
  Else
  ...
  End If

  インデントを設定すると、読みやすいコードになります。次に例を示します。

  If ... Then
     If ... Then
     ...
     Else
     ...
     End If
  Else
  ...
  End If

• コメントとコードの行の最大長を定めます。これによって、ソース コード エディタでスクロールする必要がなくなり、ハード コピーの体裁も整います。
• ほとんどの演算子の前後には空白を使用します。ただし、空白によってコードの意味が変わらない場合に限ります。たとえば、C++ で使用されるポインタ表記などは例外です。
• 空白を使って、手掛かりとなる構造をソース コードに与えます。これによって、コードに "段落" が作成され、ソフトウェアの論理的な区分が理解しやすくなります。
• 複数行にわたる行では、行の途中であることを明確に示すために、各行の行末に連結演算子を置きます。行頭には置きません。
• 1 行に複数のステートメントを置くことは避けます。ただし、それが適切な場合に限ります。たとえば、for (i = 0; i < 100; i++) など、C、C++、C#、または JScript のループは例外です。
• HTML を記述するときは、タグと属性の標準書式を定めます。たとえば、タグは大文字形式で表し、属性はすべて小文字で表すと定めます。また、XHTML 仕様に従うことによっても、すべての HTML 文書の有効性を保証できます。Web ページを作成するときは、ファイル サイズとのトレードオフを考慮する必要はありますが、属性値を二重引用符で囲み、終了タグを使用するようにします。これによって、保守が簡単になります。
• SQL ステートメントを作成する場合、キーワードは大文字形式で表し、データベースの要素 (テーブル、列、ビューなど) には大文字と小文字を混ぜて使用します。
• ソース コードを複数の物理ファイルに論理的に分割します。
• 主要な SQL 句は、それぞれ別の行に記述します。これによって、読みやすく、編集しやすいステートメントになります。たとえば次のように記述します。
  SELECT FirstName, LastName
  FROM Customers
  WHERE State = 'WA'

• コードの大規模で複雑な部分は、理解しやすい小さなモジュールに分割します。

参照

コーディング技法とプログラミング技術 | プログラム構造とコード規則 | XML ドキュメント | Visual Basic の名前付け規則