読みやすいコードを書く

成功する開発チームは、チームのすべてのメンバーがコードの再利用ルールを遵守することを要求します。これらのルールは、開発者の創造性や開発効率を大幅に低下させることなく、コードの再利用性を最大限に高めます。コードを作成および使用する開発者が共通のプログラム命名規則とコード コメント要件に従う場合、コードの再利用性は大幅に向上します。これらの標準の開始点はシステム アーキテクチャ レベルです。機能仕様では、クラス、プロパティ名、関数の戻り値、およびその他の主要なプログラム要素の定義にこれらの標準を反映する必要があります。この記事では、読者が独自のコード再利用標準を開発できるようにすることを目的として、基本的な命名規則とコメントに関する実践的な提案をいくつか提供します。


大文字小文字の標準


さまざまなプログラム要素に名前を付ける正しい方法について議論する前に、まず要素の大文字と小文字を区別する最も一般的な 2 つの方法を定義しましょう。

Pascal 仕様 - No. 1 文字。 、InvoiceNumber や PrintInvoice など、ターゲット名の各単語の最初の文字も含まれます。他の文字はすべて小文字です。
Camel 仕様 - 最初の文字は大文字ではありませんが、ターゲット名の各単語の最初の文字は大文字になります (例: invoiceNumber)。他の文字はすべて小文字です。
ただし、大文字と小文字を区別する要素を使用すると、大文字と小文字を区別しないプログラミング言語で問題が発生する可能性があります。たとえば、C# 言語では大文字と小文字が区別されるため、プライベート変数employeeを呼び出すと、呼び出し元はそのパブリック プロパティEmployeeを使用できます。これらの操作は完全に合法です。ただし、Visual Basic ではエラーが発生します。VB では大文字と小文字が区別されず、VB の観点では上記 2 つの要素は同じものであるためです。言語が混在する環境で作業する場合、開発者が他の人が開発したコードを読み取るために複数の言語を合理的に使用することを要求する特定のルールのみを指定できます。


命名基準
上記の大文字と小文字の基準を採用すると仮定して、一般的なプログラム要素に対する簡単な命名案をいくつか見てみましょう。

クラス
一部のクラスは、現実世界のオブジェクトをシミュレートするように設計されており、これらのクラスでは、選択する名前は現実世界のオブジェクトを反映し、Employee、Invoice、Timecard などの単数名詞形式にする必要があります。内部クラスの場合、Pascal 仕様を使用して、結果クラスに ThreadPool や CustomColor などの単数名を付けることができます。 Employees 配列などの複数形で同じ型のコレクション名を表現できるように、クラスは単数形である必要があります。

クラスのメンバー
C# やその他の大文字と小文字を区別するプログラミング言語を使用する開発者は、クラス メンバーの名前付けに Camel 規則を使用する必要があります。そうすることで、開発者は内部変数の名前とパブリック プロパティの名前を区別しやすくなります。多くの VB 開発者は、クラス メンバーに名前を付けるためにハンガリー語の命名法を使用することを好みます。つまり、名前の前に接頭辞を追加して変数の型を示します。たとえば、sName は文字列型の Name 変数を指します。 VS.NET などの高度な開発環境では、システムのマウスを変数上に置くとシステムの変数の型が自動的に表示されるため、これを行う必要はないと思います。私は個人的に、クラス メンバー名の前に小文字の m を付けるのが好きです。このように、内部変数には十分な内部クラス情報が格納されます。内部変数 mName はパブリック属性 Name を表すだけです。

メソッド
メソッドは、Pascal 仕様に従って名前を付け、その実装動作を合理的な方法で説明する必要があります。たとえば、データベースに従業員を追加するメソッドには AddEmployee という名前を付けることができ、請求書を印刷するメソッドには PrintInvoice という名前を付けることができます。メソッドがブール値を返す場合、if ステートメントで使用したときにその意味がより明確になるように、メソッド名を動詞で始める必要があります。たとえば、従業員が会社の 401k プランの資格があるかどうかを判断するメソッドがある場合、If ステートメントで IsEligible401k メソッドを呼び出すことができます。 If IsEligible401k then...

メソッドのパラメーター、戻り値、変数
すべてメソッドのパラメータ、戻り値、および変数はすべて、Pascal 仕様に従って名前を付ける必要があります。メソッド名と同様に、パラメータまたは変数の意味も反映する必要があります。メソッドを呼び出すと Intellisense がパラメーター名とパラメーターの型を返すため、これはパラメーター メソッドの場合に特に重要です。メソッドを使用するすべての開発者は、その意味が相互に理解できるように、わかりやすい名前と型を使用する必要があります。

コントロール
コントロールの名前付けは、開発分野でしばしば議論の的となる問題です。ほとんどの人は、TextBox1 や Label1 などのコントロールのデフォルト名を使用すべきではないことに同意していますが、コントロールに変数として名前を付けることや、コントロールの種類を示すプレフィックスを使用することにも反対しています。私は、フォーム上のコントロールに名前を付けるには、標準の 3 文字の接頭辞を使用することを好みます。たとえば、姓と名を保存するテキスト ボックス コントロールには、それぞれ txtLastName と txtFirstName という名前を付けることができます。フォーム データを処理するコマンド ボタンには、cmdSubmit または cmdCancel という名前を付けることができます。実際には、コントロールの命名が一貫していて、標準が理解しやすいことが保証できる限りは可能です。

メモ
コードにコメントを付けることはすべての開発者にとって必須です。適切なアノテーション技術を教えるために、私はデモ プログラムにアノテーション付きコードを追加することがよくあります。また、注釈のプロセスを簡素化するために、開発者は最初に、作成したいプログラムを説明するコメントを書くことをお勧めします。まず、プログラム内のプロシージャ、クラス、またはその他のプログラム要素を説明するコメントを書きますが、それらがどのように機能するかについては説明しません。次に、プロセスの主要なステップやクラスの要素を説明する一連のコメント付きコードを作成します。クラスを定義したり、プロセスを説明したりするコードを作成した後、各外部変数、コントロール、開いているファイル、さらには他のプロセスによってアクセスされる要素を文書化し、入力パラメーターと戻り値を簡単に説明します。

C# を使用してプログラムを開発している場合、VS.NET 環境には、内部 C# コメントを外部 HTML ドキュメントに変換するのに役立つ組み込みツールがすでに組み込まれています。独自のドキュメントに特別な処理ディレクティブを追加して、外部ドキュメントの表現方法を変更できます。詳細については、VS.NET 内部ヘルプ ファイル ms-help://MS.VSCC/MS.MSDNVS/csref/html/vcoriXMLDocumentation.htm を参照してください。