程式碼樣式命名規則

  • 發行項

在 .editorconfig 檔案中，您可以定義 .NET 程式設計語言程式碼專案的命名慣例，例如類別、屬性和方法，以及編譯器或 IDE 應如何強制執行這些慣例。 例如，您可以指定未大寫的公用成員應該視為編譯器錯誤，或如果私用欄位不是以 開頭 _ ，則應該發出組建警告。

具體來說，您可以定義命名規則 ，其中包含三個 部分：

  • 規則 套用至的符號群組 ，例如公用成員或私用欄位。
  • 要 與規則建立關聯的命名樣式 ，例如名稱必須大寫或以底線開頭。
  • 當符號群組中包含的程式碼專案未遵循命名樣式時，訊息的嚴重性層級。

一般語法

若要定義上述任何實體，即命名規則、符號群組或命名樣式，請使用下列語法來設定一或多個屬性：

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

指定 kind 的所有屬性設定，並 entityName 組成該特定實體定義。

每個屬性應該只設定一次，但某些設定允許多個逗號分隔值。

屬性的順序不重要。

<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>

<entityName > 是您選擇的描述性名稱，可將多個屬性設定關聯至單一定義。 例如，下列屬性會產生兩個符號群組定義， interface 而 types 每個定義都有兩個屬性。

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>

每種實體， 命名規則 、 符號群組 或 命名樣式 ，都有自己的支援屬性，如下列各節所述。

符號群組屬性

您可以設定符號群組的下列屬性，以限制群組中包含哪些符號。 若要指定單一屬性的多個值，請以逗號分隔值。

屬性 說明 允許的值 必要
applicable_kinds 群組 1 中的符號種類 *(請使用此值來指定所有符號)
namespace
class
struct
interface
enum
property
method
field
event
delegate
parameter
type_parameter
local
local_function		 Yes
applicable_accessibilities 群組中符號的協助工具層級 * (請使用此值來指定所有存取層級)
public
internal 或 friend
private
protected
protected_internal 或 protected_friend
private_protected
local （針對方法內定義的符號）		 Yes
required_modifiers 只比對所有 指定修飾詞 2 的符號 abstract 或 must_inherit
async
const
readonly
static或 shared 3		 No

注意：

  1. 目前 applicable_kinds 不支援 Tuple 成員。
  2. 符號群組會 比對 屬性中的所有 required_modifiers 修飾詞。 如果您省略這個屬性，則比對不需要特定的修飾詞。 這表示不論是否套用此規則，符號的修飾詞都不會造成影響。
  3. 如果您的群組在 static 屬性中有 required_modifiers 或 shared ，群組也會包含 const 符號，因為它們是隱含的 /staticShared 。 不過，如果您不想將 static 命名規則套用至 const 符號，您可以使用 的符號群組 const 來建立新的命名規則。 新的規則會根據規則順序 優先 。
  4. class 包含 C# 記錄 。

命名樣式屬性

命名樣式會定義您想要使用規則強制執行的慣例。 例如：

  • 使用 大寫 PascalCase
  • 開頭為 m_
  • 結尾為 _g
  • 使用 分隔單字 __

您可以為命名樣式設定下列屬性：

屬性 說明 允許的值 必要
capitalization 符號內單字大寫樣式 pascal_case
camel_case
first_word_upper
all_upper
all_lower		 是1
required_prefix 必須以這些字元開頭 No
required_suffix 必須以這些字元結尾 No
word_separator 符號內的單字必須用這個字元分隔 No

注意：

  1. 您必須將大寫樣式指定為您命名樣式的一部分，否則您的命名樣式可能會遭到忽略。

命名規則屬性

規則的所有命名規則屬性都必須生效。

屬性 說明
symbols 在其他地方定義的符號群組名稱;命名規則將套用至此群組中的符號
style 應該與此規則相關聯的命名樣式名稱;樣式定義于別處
severity 設定要強制執行命名規則的嚴重性。 將相關聯的值設定為其中一個可用的 嚴重性層級 。 1

注意：

  1. 命名規則內的嚴重性規格只會在開發 IDE 內受到尊重，例如 Visual Studio。 C# 或 VB 編譯器無法瞭解此設定，因此在建置期間不會受到尊重。 若要在組建上強制執行命名樣式規則，您應該改用程式 代碼規則嚴重 性設定來設定嚴重性。 如需詳細資訊，請參閱這個 GitHub 問題。

規則順序

EditorConfig 檔案中定義命名規則的順序並不重要。 命名規則會根據規則本身的定義自動排序。 關於協助工具、修飾詞和符號的更特定規則優先于較不特定的規則。 如果規則之間有重迭，或規則排序造成問題，您可以將這兩個規則的交集分成一個新的規則，其優先順序高於其衍生來源的更廣泛規則。 如需範例，請參閱 範例：重迭命名策略 和 範例： const 修飾詞包含 static 和 readonly 。

EditorConfig 語言服務延伸模組 可以分析 EditorConfig 檔案，並報告檔案中的規則順序與編譯器在執行時間將使用的專案不同的情況。

注意

如果您使用 Visual Studio 2019 之前的 Visual Studio 版本，則命名規則應該從 EditorConfig 檔案中最特定到最不特定的排序。 第一個遇到的可套用規則，會是唯一套用的規則。 但是，如果有多個具有相同名稱的規則屬性，則最近找到具有該名稱的屬性優先。 如需詳細資訊，請參閱檔案階層和優先順序。

範例：重迭命名策略

請考慮下列兩個命名規則：

  1. 公用方法是 PascalCase。
  2. 非同步方法結尾為 "Async" 。

對於 public async 方法而言，不明顯哪一個規則優先。 您可以為 public async 方法建立新的規則，並確切指定命名。

範例： const 修飾詞包含 static 和 readonly

請考慮下列兩個命名規則：

  1. 常數位段為 PascalCase。
  2. 非公用 static 欄位s_camelCase。

規則 2 更具體且優先，因此所有非公用常數位段都會s_camelCase。 若要解決此問題，您可以定義交集規則：非公用常數位段為 PascalCase。

預設命名樣式

如果您未指定任何自訂命名規則，則會使用下列預設樣式：

  • 對於具有任何協助工具的類別、結構、列舉、屬性、方法和事件，預設命名樣式為 Pascal 大小寫。

  • 對於具有任何協助工具的介面，預設命名樣式是 Pascal 大小寫，其前置詞 為 I 。

程式碼規則識別碼： IDE1006 (Naming rule violation)

所有命名選項都有規則識別碼 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 ），所以您必須定義兩個命名規則：

  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_underscoredprivate_static_fields_none 使用命名樣式。

另請參閱