ベストなコーディング規約の作り方

第2版　リンク削除。見やすく編集。一部加筆。

#コーディング規約とは

「コーディング規約」は多数のプログラマが参加するプロジェクトにおいて、プログラミング品質を均等にするために定める文書です。

内容は変数などの命名規則、禁止事項 (例えば goto 文はダメとか)、コメントの付け方とか、いろいろプロジェクトの特性やその会社の文化などで変わります。

#コーディング規約のメリット・デメリット

コーディング規約のメリットはプログラマの個性を殺して均質なプログラムを作ること、過去の知識や経験から得られたバグの発生源となりやすいコーディングの防止、インデントやコメントの基準を決めて見やすさ保守性の高さを求める・・・等々です。

一方、デメリットですが、使える文法を制限してスキルの高いプログラマの生産性を殺したり、過去のプログラムとの互換性を追求するあまり新しい機能の使用を制限したり・・・等々があります。

一般に、大きなプロジェクトほどコーディング規約の内容は強制的、制限的です。これは、大きなプロジェクトだと、スキルの低い人もメンバーに入っていることが多く、コーディングを自由にやらせると、品質が落ちたり、プログラムが見づらく保守性が悪くなったりするためです。

#コーディング規約の内容

コーディング規約の内容は、プロジェクトの規模や特性、参加メンバーのスキル、使用言語などにより変更すべきですが、たいていこんな内容が書かれています。

• 目的
• プロジェクトの構成
• 命名規則
• コーディングスタイル
• 禁止事項
• 制限事項
• 推奨事項

##目的

そのコーディング規約の適用範囲、なぜ必要なのか、それを守ることによりどんなメリットがあるかを書きます。

##プロジェクトの構成

コーディングにはあまり関係なさそうな内容ですが、ソースプログラムの先頭にコメントを入れたりするのに使います。プロジェクトの名称などはあらかじめ決まっていることが多いので、もし、そうなら一覧表を付けます。メタ情報の指定方法、フォルダの構成方法なども決めておきます。

##命名規則

変数、定数、メソッド(関数)、クラスなどの名前の付け方の基準を決める。変数名の先頭は小文字だとか、クラス名の先頭は大文字だとかがよく使われます。

##コーディングスタイル

コーディングスタイルはインデントの仕方とか、中かっこの位置とか、コメントの位置や内容とかを決めておきます。

##リソース

エラーメッセージなどはハードコーディングしないで、よくリソースファイルのインデックスを指定したりします。もし使うなら、リソースの使用についての説明、制限なども書いておきましょう。（あまり大きいリソースの管理はたいへんなのでバランスを考えたほうがいいです。特に IDE を使う場合。）

##禁止事項

使ってはいけない文法や今はほとんど使われない保守用になっているものとかを挙げておきます。一律に禁止でなく、場合によっては例外も設けておきます。(なぜ禁止なのか、その理由も必ず書きます)

##制限事項

あまり推奨されない機能、コーディング方法、クラスなどを揚げておきます。また、その条件を明示します。

##推奨事項

好ましいコーディング方法や複数の似たようなクラスや関数などがある場合、どちらが推奨されるかを書いておきます。

#コーディング規約を作るときの注意

##短く見やすく

コーディング規約は、できるだけ短いほうがよいのであまり盛りだくさんにしないようにします。メンバーのスキルが高い場合は、最低限の内容にした方が生産性が上がります。内容が全員によく伝わるようにサンプルを付けましょう。また、禁止事項、制限事項など、なぜそうなのかの理由も必ず書いておきましょう。

##プロジェクトに合わせて作る

コーディング規約は、どこかの管理部門みたいなところが作ったのをそのまま使うのはよくありません。なぜなら、技術的に古くなっていたり、そのプロジェクトに最適になっていないためです。

例えば、メンバーのスキルが高い場合は、コーディング規約はできるだけ薄いほうがいいです。高スキル者にいろいろ規約を守らせようとすると、生産性が大幅に落ちてしまいせっかく高スキル者を集めた意味がありません。

逆に、低スキル者中心のプロジェクトならたとえ量が多くなっても、詳しく書いたほうがいいですね。もう、そうなるとコーディング規約と言うより、「コーディング指南書」みたいな性格にします。この場合は、高品質なサンプルをたくさん付けましょう。

高スキル者、低スキル者が入り混じった大きなプロジェクトでは、例外を多く認めて高スキル者の生産性を奪わないようにしましょう。

##テストに対する考慮

最後に忘れてはならないのが、テストに対する考慮です。テストはプロジェクトで大きな時間を占めます。この時間を以下に減らせるかが、プロジェクトの明暗を決めます。テストのしやすさ、バグの検出のしやすさなどを考慮しましょう。

##作る人

コーディング規約を作る人は相当なスキルが求められます。プロジェクトで使用する言語や環境などに対して精通している必要があります。そうでないと、「ぬけ」があったり(セキュリティに関する抜けは致命的)、禁止事項などが多すぎて開発の効率が落ちたりしてしまいます。

#VB.NET版のサンプルを作ってみました
たたき台程度の内容ですが、参考になればと思います。
あと、用例も入れたほうがいいですね。

#VB.NET コーディング規約サンプル

##目的

この文書は、VB.NET 新人プログラマが、コーディングにおいて留意すべき事項にまとめたものである。

##プロジェクト

このルールはプロジェクトごとにそのプロジェクトの性格、メンバー構成、規模、難易度などを考慮し、カスタマイズして使用するものとする。

##命名規約

###原則

クラスや変数等の命名については、原則、MSDN のサンプルコードを参考にすること。

###個別規約

• クラス、モジュール、メソッド、プロパティ、名前空間などは英単語を基本とし大文字で始まるものとする。複数単語からなる場合は、単語の先頭は大文字、それ以外は小文字とする。_ や数字は使用しない。(理由：習慣による)
• ※ スペルが間違っているとみっともないので自信がないものは確認すること。
• 変数名は基本的に小文字で始まるものとする。複数単語からなる変数名の場合は、２つめ以降の単語の先頭は大文字にする。(理由：習慣による)
• 名前はその変数の使用目的を考慮し、わかりやすい名前を付けること。(理由: わかりやすさのため)
• 名前に英単語と日本語を混在したり、日本語のローマ字は使わないこと。(理由: オフショア開発にそのコードを流用した場合、海外のプログラマが意味を理解できない)
• １文字または２文字など短い変数名を使用する場合は、下記の原則に従うこと。短い変数名はメソッド内のみで使用すること。(理由：習慣による)
• For や While ループでのインデックス(カウンタ)として使う変数は、i, j, k を使う。その際、一番外側のループから順に i, j, k を使用すること。
• ワーク用座標は x, y を使用すること。
• ワーク用文字列は s あるいは s から始まること。
• ワーク用オブジェクトは o から始まること。１文字の o, O (小文字と大文字のオー) は 0 と似ているので使用しないこと。
• l (小文字のエル) は１と区別しにくいので使用しないこと。
• 日本語 (漢字、ひらがな等) のクラス名や変数名は原則使用しないこと。(理由: 海外版のソフトで文字化けの可能性、オフショア開発で海外プログラマが意味を理解できない)
• すべて大文字の名前は定数のみ使用できるものとする。これには Enum のメンバーを含む。(理由：習慣による)
• すべて小文字の名前はメソッド(プロパティを含む)内のみ使用できる。(理由：習慣による)
• キーワードと同じ名前の変数は使用しないこと。(理由：バグの原因になるため)
• ※ キーワードによっては変数として使ってもコンパイルエラーにならないものがある。
• (注意) Visual Basic は過去の互換性ため大文字と小文字を区別しない。例えば If, if, IF のどれもコンパイルエラーにはならない。

##コーディングスタイル

###原則

コーディングスタイルについては、原則、MSDN のサンプルコードを参考にすること。

また、Visual Studio のデフォルトのフォーマッタ機能によるスタイルを変更しないこと。

###個別規約

• 機能ごとに #Region を使用して Visual Studio で折り畳み表示ができるようにすること。(理由：見やすさ、開発の効率性)
• 基本的に #If を使用しないこと。(理由：削除を忘れた時の意図しないバグの可能性)
• デバッグ中に一時的に使用する場合は、デバッグ完了時に削除すること。
• １００行を超えるような長いメソッドは作らないこと。そのような場合は、いくつかのメソッドに分ける。(理由：見やすさ、バグ発生時の検出のしやすさ)
• 入れ子は最大でも３段階(推奨２段階まで)とする。(理由：見やすさのため)
• ブロック内のコードは最大でも５０行程度とする。(理由：見やすさのため)
• メソッドの引数には、必ず ByVal (場合によっては ByRef) を付けること。(理由：あいまいさの除去)
• クラスやメソッドには、必ず Public や Private などを付けること。(理由：あいまいさの除去)
• マジックナンバーは原則使用しないこと。代わりに定数や Enum を使用する。
• [マジックナンバーの例] i = 100 などと書いたとき、この 100 が何を意味するのが分からない。ただし、初期化のための、i = 0 や s = "" は例外とする。
• 例外は最上位のクラスでキャッチすること。(理由：例外処理の統一性)
• 特別な場合を除き、条件判定で And の代わりに AndAlso、Or の代わりに OrElse を使用すること。(理由：副作用の防止、高速化)
• Dim はメソッド内のみで使用する。(理由：あいまいさの除去)
• 独自の Partial クラスは使用しないこと。(理由：見やすさのため)
• 独自の拡張メソッドを使用するときは、必ずコメントを入れて拡張メソッドであることを明確にすること。(理由：見やすさのため)
• 独自例外は原則使用しないこと。使用する場合は、必ず例外オブジェクトを定義すること。(理由：保守の容易性)

###コメント

• クラス、モジュール、メソッド、プロパティ、クラスの変数にはコメントを入れて説明すること。これらのコメントは後でヘルプファイルを自動生成するため、''' で始める XML コメントとする。
• summery コメントには、そのクラス等の機能概要を記述すること。
• メソッドの引数 (param コメント) には、その引数の機能や意味を記述すること。ただし、標準のイベントハンドラなどで引数の意味が既知の場合は省略してもよい。
• remarks コメントには、機能詳細や備考を記述する。コードが短いメソッドやプロパティの場合は省略してよいが、原則、記述すること。
• メソッドやプロパティ内部にも、わかりやすさのために機能単位にコメントを入れること。
• 既存のコードを修正したとき、変更が必要な他のコメントも同時に変更すること(理由：変更箇所以外のコメントもたいてい変更が出るため)。同時に、意味がなくなったコメントは削除すること。
• ※ 通常、バージョン管理システムにより古いソースを取得できる。
• コードの意味と関係ないコメントは原則不要とする(プロジェクトの方針に依存)。一時的なものはリリースまでに必ず削除する。
• (例) TODO: .... や 何年何月 誰々さん追加など。
• 不要となった行のコメントアウトはリリースまでに必ず削除する。
• 変更履歴などのコメントはファイルの先頭にまとめる。
• コメントがあまり多いとソースの可読性が低下するので、プロジェクトとして古いコメントの削除方針を決める。

###リソース

• アプリケーションで共通に使用するメッセージ、画像などはリソースに格納する。同様にアプリケーションの設定値は設定ファイルに格納する。
• 環境変数はアプリケーション共通の場合を除いて、使用禁止とする。
• アプリケーションの諸元やバージョン番号は、プロジェクトの基本方針に基づいてプロジェクトのプロパティに書く。

###禁止事項

• ネットで検索したサンプルプログラムのコードをむやみにコピーして使わないこと。(理由：信頼性の欠如)
• サンプルプログラムをコピーして使う場合は、出所をコメントとして明示する。また、サンプルプログラムの動作確認を単体で行うこと。
• 古いコレクションクラスを使用しないこと(例：ArrayList クラス)。代わりに Generic コレクションクラスを使用する。(理由：要素の型があいまいになる、古いコードの除去)
• デバッグやテストのためのコードはテスト完了後そのまま(コメントアウトなど)にしないこと。(理由：保守性の向上)

###制限事項

• GoTo 文は深い入れ子から脱出するときのみ使用できる。(理由：コードの見易さ)
• With 文は入れ子にしてはならない。(理由：コードの見易さ、あいまいさの除去)
• クラシック Visual Basic 互換関数は簡単な代替手段がある場合は使用しない。(理由：古いコードの除去、あいまいさの除去)
• [例] Asc(c) でなく Convert.ToInt32(c) を使用する。
• ReDim 文は原則使用しない。代わりに List(Of ..) を使用する。(理由：古いコードの除去)

###推奨事項

• 変数を宣言するときは、型の指定を行う。(無意味でない場合を除き、同時に初期化するほうがよい)
• ローカル変数の宣言は原則メソッドの先頭で行う。

//