コードスタイルの名前付けルール

  • [アーティクル]

.editorconfig ファイルでは、.NET プログラミング言語のコード要素 (クラス、プロパティ、メソッドなど) の名前付け規則と、コンパイラまたは IDE でそれらの規則を適用する方法を定義できます。 たとえば、大文字になっていないパブリック メンバーはコンパイラ エラーとして扱う必要がある、またはプライベート フィールドが _ で始まっていない場合はビルド警告を発行する必要がある、などと指定できます。

具体的には、3 つの部分で構成される名前付けルールを定義できます。

  • ルールの適用先となるシンボル グループ (例: パブリック メンバー、プライベート フィールド)。
  • ルールと関連付けられる名前付けスタイル (例: 名前は大文字にしなければならない、アンダースコアで始まる必要がある)。
  • シンボル グループに含まれるコード要素が名前付けスタイルに従っていないときのメッセージの重大度レベル。

一般的な構文

上記のエンティティ (名前付けルール、シンボル グループ、または名前付けスタイル) のいずれかを定義するには、次の構文を使って 1 つ以上のプロパティを設定します。

<kind>.<entityName>.<propertyName> = <propertyValue>

特定の kind と entityName に対するすべてのプロパティ設定により、その特定のエンティティの定義が構成されます。

各プロパティは一度だけ設定する必要がありますが、一部の設定では複数のコンマ区切り値も使用できます。

プロパティの順序は重要ではありません。

<kind> の値

<kind> は、定義するエンティティの種類 (名前付けルール、シンボル グループ、または名前付けスタイル) を指定し、次のいずれかである必要があります。

設定対象のプロパティ 使用する <kind> の値 例
名前付けルール dotnet_naming_rule dotnet_naming_rule.types_should_be_pascal_case.severity = suggestion
シンボル グループ dotnet_naming_symbols dotnet_naming_symbols.interface.applicable_kinds = interface
名前付けスタイル dotnet_naming_style dotnet_naming_style.pascal_case.capitalization = pascal_case

<エンティティ名>

<entityName> は、複数のプロパティ設定を 1 つの定義に関連付ける、自由に選択できるわかりやすい名前です。 たとえば、次のプロパティでは、interface と types という 2 つのシンボル グループ定義が生成され、そのそれぞれに 2 つのプロパティが設定されています。

dotnet_naming_symbols.interface.applicable_kinds = interface
dotnet_naming_symbols.interface.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected

dotnet_naming_symbols.types.applicable_kinds = class, struct, interface, enum, delegate
dotnet_naming_symbols.types.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected

<propertyName> と <propertyValue>

エンティティの各種類 (名前付けルール、シンボル グループ、または名前付けスタイル) には、サポートされる独自のプロパティがあります。これについては、次のセクションで説明します。

シンボル グループのプロパティ

シンボル グループに対しては、次のプロパティを設定して、グループに含めるシンボルを制限できます。 1 つのプロパティに複数の値を指定するには、値をコンマで区切ります。

プロパティ 説明 使用できる値 必須
applicable_kinds グループ内のシンボルの種類 1 *(この値を使用すると、すべてのシンボルが指定されます)
namespace
class
struct
interface
enum
property
method
field
event
delegate
parameter
type_parameter
local
local_function		 はい
applicable_accessibilities グループ内のシンボルのアクセシビリティ レベル *(この値を使用すると、すべてのアクセシビリティ レベルが指定されます)
public
internal または friend
private
protected
protected_internal または protected_friend
private_protected
local (メソッド内で定義されたシンボルの場合)		 はい
required_modifiers 指定した修飾子を "すべて" 持つシンボルとのみ一致 2 abstract または must_inherit
async
const
readonly
static または shared3		 いいえ

注:

  1. タプル メンバーは、今のところ applicable_kinds ではサポートされていません。
  2. このシンボル グループは、required_modifiers プロパティに含まれる "すべて" の修飾子と一致します。 このプロパティを省略すると、一致するために特定の修飾子が必要とされなくなります。 このことは、この規則が適用されるかどうかに、シンボルの修飾子が影響を及ぼさないことを意味します。
  3. required_modifiers プロパティに static または shared があるグループの場合、そのグループには const シンボルも含まれます。これは、それらのシンボルが暗黙的に static/Shared であるためです。 ただし、static 名前付けルールが const シンボルに適用されないようにしたい場合は、const のシンボル グループを使用して新しい名前付けルールを作成できます。 新しいルールは、ルールの順序に従って優先されます。
  4. class には C# レコードが含まれます。

名前付けスタイルのプロパティ

名前付けスタイルは、そのルールで適用する規則を定義します。 次に例を示します。

  • PascalCase で大文字にする
  • m_ で始まる
  • _g で終わる
  • __ で単語を区切る

名前付けスタイルには、次のプロパティを設定できます。

プロパティ 説明 使用できる値 必須
capitalization シンボル内の単語の大文字/小文字スタイル pascal_case
camel_case
first_word_upper
all_upper
all_lower		 可1
required_prefix この文字で始まる必要がある いいえ
required_suffix この文字で終わる必要がある いいえ
word_separator このシンボル内の単語は、この文字で区切る必要がある いいえ

注:

  1. 名前付けスタイルの一部として大文字/小文字スタイルを指定する必要があります。そうしないと、名前付けスタイルは無視される可能性があります。

名前付けルールのプロパティ

ルールを有効にするには、すべての名前付けルール プロパティが必要です。

プロパティ 説明
symbols 他の場所で定義されているシンボル グループの名前。名前付けルールは、このグループ内のシンボルに適用されます
style このルールに関連付ける必要がある名前付けスタイルの名前。スタイルは他の場所で定義されています
severity 名前付けルールを適用する際の重大度を設定します。 関連する値を、使用可能な重大度レベルのいずれかに設定します。1

注:

  1. 名前付けルール内での重大度指定は、Visual Studio などの開発 IDE 内でのみ遵守されます。 この設定は、C# や VB のコンパイラでは認識されないため、ビルド時には遵守されません。 ビルドで名前付けスタイル ルールを適用するには、代わりにコード ルールの重大度構成を使用して重大度を設定する必要があります。 詳細については、こちらの GitHub の問題のページを参照してください。

ルールの順序

EditorConfig ファイルで名前付けルールを定義する順序に意味はありません。 名前付けルールは、ルール自体の定義に従って自動的に並べ替えられます。 アクセシビリティ、修飾子、シンボルに関するより具体的なルールが、より一般的なルールよりも優先されます。 ルール間に重複がある場合、またはルールの順序が問題を引き起こす場合は、2 つのルールの共通部分を取り出して、その元のより広範なルールよりも優先される新しいルールを作成できます。 例については、「例: 重複する名前付けの戦略」と「例: const 修飾子には static と readonly が含まれる」を参照してください。

EditorConfig 言語サービス拡張機能では、EditorConfig ファイルを分析して、ファイルでの規則の順序が実行時にコンパイラで使用される順序と異なる場合に報告できます。

Note

Visual Studio 2019 バージョン 16.2 より前のバージョンの Visual Studio を使用している場合は、EditorConfig ファイル内で、最も限定的なものから最も限定的でないものの順に名前付けルールを並べ替える必要があります。 適用可能な最初に検出されたルールのみが適用されます。 ただし、同じ名前のルールの "プロパティ" が複数ある場合は、その名前の最も最近見つかったプロパティが優先されます。 詳細については、「File hierarchy and precedence (ファイルの階層と優先順位)」を参照してください。

重複する名前付けの戦略

次の 2 つの名前付けルールについて考えてみましょう。

  1. パブリック メソッドは PascalCase。
  2. 非同期メソッドは "Async" で終わる。

public async メソッドの場合、どちらのルールが優先されるかは明確ではありません。 public async メソッド用の新しいルール作成し、名前付けを正確に指定できます。

例: const 修飾子には static と readonly が含まれる

次の 2 つの名前付けルールについて考えてみましょう。

  1. 定数フィールドは PascalCase。
  2. パブリックでない static フィールドは s_camelCase。

ルール 2 の方が具体的なので優先されます。そのため、すべてのパブリックでない定数フィールドが s_camelCase になります。 この問題を解決するには、次の共通部分のルールを定義できます: パブリックでない定数フィールドは PascalCase。

既定の名前付けスタイル

カスタムの名前付けルールをまったく指定しない場合は、次の既定のスタイルが使用されます。

  • アクセシビリティがあるクラス、構造体、列挙型、プロパティ、メソッド、およびイベントでは、既定の名前付けスタイルはパスカル ケースです。

  • アクセシビリティがあるインターフェイスでは、既定の名前付けスタイルはパスカル ケースであり、プレフィックス I を付ける必要があります。

コード ルール ID: IDE1006 (Naming rule violation)

すべての名前付けオプションにルール ID IDE1006 とタイトル Naming rule violation が指定されます。 EditorConfig ファイルで次の構文を使用して、名前付け違反の重大度をグローバルに構成できます。

dotnet_diagnostic.IDE1006.severity = <severity value>

ビルド時に適用するには、重大度の値を warning または error にする必要があります。 使用できるすべての重大度の値については、「重大度レベル」を参照してください。

例: パブリック メンバーの大文字の使用

次の .editorconfig ファイルには、readonly とマークされたパブリック プロパティ、メソッド、フィールド、イベント、デリゲートは大文字で入力する必要があることを指定した名前付け規則が含まれています。 この名前付け規則では、規則を適用する複数の種類のシンボルを、コンマを使って各値を区切ることで指定しています。

[*.{cs,vb}]

# Defining the 'public_symbols' symbol group
dotnet_naming_symbols.public_symbols.applicable_kinds           = property,method,field,event,delegate
dotnet_naming_symbols.public_symbols.applicable_accessibilities = public
dotnet_naming_symbols.public_symbols.required_modifiers         = readonly

# Defining the 'first_word_upper_case_style' naming style
dotnet_naming_style.first_word_upper_case_style.capitalization = first_word_upper

# Defining the 'public_members_must_be_capitalized' naming rule, by setting the
# symbol group to the 'public symbols' symbol group,
dotnet_naming_rule.public_members_must_be_capitalized.symbols  = public_symbols
# setting the naming style to the 'first_word_upper_case_style' naming style,
dotnet_naming_rule.public_members_must_be_capitalized.style    = first_word_upper_case_style
# and setting the severity.
dotnet_naming_rule.public_members_must_be_capitalized.severity = suggestion

例: アンダースコアが含まれるプライベート インスタンス フィールド

この .editorconfig ファイル スニペットは、プライベート インスタンス フィールドが _ で始まる必要があることを強制します。その規則に従っていない場合、IDE はそれをコンパイラ エラーとして扱います。 プライベート静的フィールドは無視されます。

シンボル グループは、使われている識別子に基づいてのみ定義でき (たとえば、static やreadonly)、使われていない識別子では定義できないので (たとえば、static がないことを理由とするインスタンス フィールドなど)、2 つの名前付けルールを定義する必要があります。

  1. すべてのプライベート フィールド (static またはなし) では、適用された underscored 名前付けスタイルを、コンパイラ error する必要があります。
  2. static が指定されたプライベート フィールドでは、適用された underscored 名前付けスタイルを、none の重大度レベルにする必要があります。つまり、このケースを無視します。
[*.{cs,vb}]

# Define the 'private_fields' symbol group:
dotnet_naming_symbols.private_fields.applicable_kinds = field
dotnet_naming_symbols.private_fields.applicable_accessibilities = private

# Define the 'private_static_fields' symbol group
dotnet_naming_symbols.private_static_fields.applicable_kinds = field
dotnet_naming_symbols.private_static_fields.applicable_accessibilities = private
dotnet_naming_symbols.private_static_fields.required_modifiers = static

# Define the 'underscored' naming style
dotnet_naming_style.underscored.capitalization = pascal_case
dotnet_naming_style.underscored.required_prefix = _

# Define the 'private_fields_underscored' naming rule
dotnet_naming_rule.private_fields_underscored.symbols = private_fields
dotnet_naming_rule.private_fields_underscored.style = underscored
dotnet_naming_rule.private_fields_underscored.severity = error

# Define the 'private_static_fields_none' naming rule
dotnet_naming_rule.private_static_fields_none.symbols = private_static_fields
dotnet_naming_rule.private_static_fields_none.style = underscored
dotnet_naming_rule.private_static_fields_none.severity = none

この例は、エンティティ定義を再利用できることも示されています。 underscored 名前付けスタイルは、private_fields_underscored と private_static_fields_none の両方の名前付けルールで使われています。

関連項目