Udostępnij za pośrednictwem

Reguły nazewnictwa stylu kodu

  • Artykuł

W pliku .editorconfig można zdefiniować konwencje nazewnictwa dla elementów kodu języka programowania .NET, takich jak klasy, właściwości i metody , oraz sposób wymuszania tych konwencji przez kompilator lub środowisko IDE. Można na przykład określić, że publiczny element członkowski, który nie jest kapitalizowany, powinien być traktowany jako błąd kompilatora lub jeśli pole prywatne nie zaczyna się od _, powinno zostać wyświetlone ostrzeżenie kompilacji.

W szczególności można zdefiniować regułę nazewnictwa, która składa się z trzech części:

  • Grupa symboli, która ma zastosowanie do na przykład publicznych elementów członkowskich lub pól prywatnych.
  • Styl nazewnictwa do skojarzenia z regułą, na przykład, że nazwa musi być wielkich liter lub zaczynać się od podkreślenia.
  • Poziom ważności komunikatu, gdy elementy kodu zawarte w grupie symboli nie są zgodne ze stylem nazewnictwa.

Składnia ogólna

Aby zdefiniować dowolną z powyższych jednostek — regułę nazewnictwa, grupę symboli lub styl nazewnictwa — ustaw co najmniej jedną właściwość przy użyciu następującej składni:

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

Wszystkie ustawienia właściwości dla danej kind jednostki i entityName składają się na daną definicję jednostki.

Każda właściwość powinna być ustawiana tylko raz, ale niektóre ustawienia zezwalają na wiele wartości rozdzielanych przecinkami.

Kolejność właściwości nie jest ważna.

<wartości kind>

<kind> określa, jaki rodzaj jednostki jest definiowany — reguła nazewnictwa, grupa symboli lub styl nazewnictwa — i musi być jednym z następujących elementów:

Aby ustawić właściwość dla <Użyj wartości rodzaju> Przykład
Reguła nazewnictwa dotnet_naming_rule dotnet_naming_rule.types_should_be_pascal_case.severity = suggestion
Grupa symboli dotnet_naming_symbols dotnet_naming_symbols.interface.applicable_kinds = interface
Styl nazewnictwa dotnet_naming_style dotnet_naming_style.pascal_case.capitalization = pascal_case

<entityName>

<entityName> to opisowa nazwa, która kojarzy wiele ustawień właściwości z pojedynczą definicją. Na przykład następujące właściwości tworzą dwie definicje grup symboli i interface types, z których każda ma dwie właściwości ustawione.

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

Każdy rodzaj jednostki — reguła nazewnictwa, grupa symboli lub styl nazewnictwa — ma własne obsługiwane właściwości, zgodnie z opisem w poniższych sekcjach.

Właściwości grupy symboli

Możesz ustawić następujące właściwości dla grup symboli, aby ograniczyć, które symbole są zawarte w grupie. Aby określić wiele wartości dla jednej właściwości, należy oddzielić wartości przecinkami.

Właściwości opis Dozwolone wartości Wymagania
applicable_kinds Rodzaje symboli w grupie 1 * (użyj tej wartości, aby określić wszystkie symbole)
namespace
class
struct
interface
enum
property
method
field
event
delegate
parameter
type_parameter
local
local_function		 Tak
applicable_accessibilities Poziomy ułatwień dostępu symboli w grupie * (użyj tej wartości, aby określić wszystkie poziomy ułatwień dostępu)
public
internal lub friend
private
protected
protected_internal lub protected_friend
private_protected
local (dla symboli zdefiniowanych w metodzie)		 Tak
required_modifiers Dopasowuje tylko symbole ze wszystkimi określonymi modyfikatorami 2 abstract lub must_inherit
async
const
readonly
static lub shared 3		 Nie.

Uwagi:

  1. Członkowie krotki nie są obecnie obsługiwane w systemie applicable_kinds.
  2. Grupa symboli pasuje do wszystkich modyfikatorów we required_modifiers właściwości . Jeśli pominiesz tę właściwość, dla dopasowania nie są wymagane żadne określone modyfikatory. Oznacza to, że modyfikatory symboli nie mają wpływu na to, czy ta reguła jest stosowana.
  3. Jeśli grupa ma static właściwość lub shared w required_modifiers niej, grupa będzie również zawierać const symbole, ponieważ są niejawnie static/Shared. Jeśli jednak nie chcesz, aby reguła static nazewnictwa miała być stosowana do const symboli, możesz utworzyć nową regułę nazewnictwa z grupą symboli const. Nowa reguła będzie mieć pierwszeństwo zgodnie z kolejnością reguł.
  4. class zawiera rekordy języka C#.

Właściwości stylu nazewnictwa

Styl nazewnictwa definiuje konwencje, które mają być wymuszane za pomocą reguły. Na przykład:

  • Wielką literą za pomocą polecenia PascalCase
  • Rozpoczyna się od m_
  • Kończy się na _g
  • Oddzielanie wyrazów z __

Dla stylu nazewnictwa można ustawić następujące właściwości:

Właściwości opis Dozwolone wartości Wymagania
capitalization Styl wielkich liter dla wyrazów w symbolu pascal_case
camel_case
first_word_upper
all_upper
all_lower		 Tak1
required_prefix Musi zaczynać się od tych znaków Nie.
required_suffix Musi kończyć się tymi znakami Nie.
word_separator Wyrazy w symbolu muszą być oddzielone tym znakiem Nie.

Uwagi:

  1. Musisz określić styl wielkich liter w ramach stylu nazewnictwa. W przeciwnym razie styl nazewnictwa może być ignorowany.

Właściwości reguły nazewnictwa

Wszystkie właściwości reguły nazewnictwa są wymagane, aby reguła weszła w życie.

Właściwości opis
symbols Nazwa grupy symboli zdefiniowanej gdzie indziej; reguła nazewnictwa zostanie zastosowana do symboli w tej grupie
style Nazwa stylu nazewnictwa, który powinien być skojarzony z tą regułą; styl jest definiowany gdzie indziej
severity Ustawia ważność, za pomocą której ma być wymuszana reguła nazewnictwa. Ustaw skojarzona wartość na jeden z dostępnych poziomów ważności.1

Uwagi:

  1. Specyfikacja ważności w regule nazewnictwa jest uwzględniana tylko wewnątrz środowisk IDE programowania, takich jak Visual Studio. To ustawienie nie jest zrozumiałe dla kompilatorów języka C# ani VB, dlatego nie jest uwzględniane podczas kompilacji. Aby wymusić reguły stylu nazewnictwa w kompilacji, należy zamiast tego ustawić ważność przy użyciu konfiguracji ważności reguły kodu. Aby uzyskać więcej informacji, zobacz ten problem w serwisie GitHub.

Kolejność reguł

Kolejność, w jakiej reguły nazewnictwa są zdefiniowane w pliku EditorConfig, nie ma znaczenia. Reguły nazewnictwa są automatycznie uporządkowane zgodnie z definicjami reguł. Bardziej szczegółowe reguły dotyczące dostępu, modyfikatorów i symboli mają pierwszeństwo przed mniej specyficznymi regułami. Jeśli reguły nakładają się na siebie lub jeśli kolejność reguł powoduje problemy, można podzielić skrzyżowanie tych dwóch reguł na nową regułę, która ma pierwszeństwo przed szerszymi regułami, z których została utworzona. Aby zapoznać się z przykładami, zobacz Przykład: Nakładające się strategie nazewnictwa i Przykład: const modyfikator zawiera static i readonly.

Rozszerzenie EditorConfig Language Service może analizować plik EditorConfig i przypadki raportów, w których kolejność reguł w pliku różni się od tego, co kompilator będzie używać w czasie wykonywania.

Uwaga

Jeśli używasz wersji programu Visual Studio starszej niż Visual Studio 2019, reguły nazewnictwa powinny być uporządkowane od najbardziej specyficznych dla najmniej specyficznych dla pliku EditorConfig. Pierwsza napotkana reguła, którą można zastosować, to jedyna zastosowana reguła. Jeśli jednak istnieje wiele właściwości reguły o tej samej nazwie, ostatnio znaleziona właściwość o tej nazwie ma pierwszeństwo. Aby uzyskać więcej informacji, zobacz Hierarchia plików i pierwszeństwo.

Przykład: Nakładające się strategie nazewnictwa

Rozważ następujące dwie reguły nazewnictwa:

  1. Metody publiczne to PascalCase.
  2. Metody asynchroniczne kończą się ciągiem "Async".

W przypadku public async metod nie jest oczywiste, która reguła ma pierwszeństwo. Możesz utworzyć nową regułę dla public async metod i określić dokładnie nazewnictwo.

Przykład: const modyfikator zawiera static i readonly

Rozważ następujące dwie reguły nazewnictwa:

  1. Pola stałe to PascalCase.
  2. Pola inne niż publiczne static są s_camelCase.

Reguła 2 jest bardziej szczegółowa i ma pierwszeństwo, więc wszystkie pola niepubliczne są s_camelCase. Aby rozwiązać ten problem, możesz zdefiniować regułę przecięcia: pola niepubliczne stałe to PascalCase.

Domyślne style nazewnictwa

Jeśli nie określisz żadnych niestandardowych reguł nazewnictwa, zostaną użyte następujące style domyślne:

  • W przypadku klas, struktur, wyliczenia, właściwości, metod i zdarzeń z dowolnymi ułatwieniami dostępu domyślnym stylem nazewnictwa jest przypadek Pascal.

  • W przypadku interfejsów z dowolnymi ułatwieniami dostępu domyślnym stylem nazewnictwa jest przypadek Pascal z wymaganym prefiksem I.

Identyfikator reguły kodu: IDE1006 (Naming rule violation)

Wszystkie opcje nazewnictwa mają identyfikator IDE1006 reguły i tytuł Naming rule violation. Ważność naruszeń nazewnictwa można skonfigurować globalnie w pliku EditorConfig o następującej składni:

dotnet_diagnostic.IDE1006.severity = <severity value>

Wartość ważności musi być warning wymuszana na kompilacji lub error musi być wymuszana. Aby uzyskać wszystkie możliwe wartości ważności, zobacz poziom ważności.

Przykład: kapitalizowanie publicznych składowych

Poniższy plik .editorconfig zawiera konwencję nazewnictwa określającą, że właściwości publiczne, metody, pola, zdarzenia i delegaty, które są oznaczone readonly , muszą być wielkich liter. Ta konwencja nazewnictwa określa wiele rodzajów symboli, aby zastosować regułę, używając przecinka w celu oddzielenia wartości.

[*.{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

Przykład: pola wystąpienia prywatnego z podkreśleniami

Ten fragment pliku .editorconfig wymusza, że pola wystąpienia prywatnego powinny zaczynać się od elementu _. Jeśli ta konwencja nie jest zgodna, środowisko IDE będzie traktować je jako błąd kompilatora. Prywatne pola statyczne są ignorowane.

Ponieważ można zdefiniować grupę symboli tylko na podstawie identyfikatorów, które ma (na przykład static lub readonly), a nie według identyfikatorów, których nie ma (na przykład pola wystąpienia, ponieważ nie ma static), należy zdefiniować dwie reguły nazewnictwa:

  1. Wszystkie pola prywatne — static lub nie — powinny mieć underscored zastosowany styl nazewnictwa jako kompilator error.
  2. Pola prywatne z static powinny mieć underscored zastosowany styl nazewnictwa z poziomem noneważności ; innymi słowy, ignoruj ten przypadek.
[*.{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

W tym przykładzie pokazano również, że definicje jednostek można użyć ponownie. Styl underscored nazewnictwa jest używany zarówno private_fields_underscored przez reguły nazewnictwa, jak i private_static_fields_none .

Zobacz też