Pravidla pojmenování stylu kódu

  • Článek

V souboru .editorconfig můžete definovat konvence vytváření názvů pro prvky kódu programovacího jazyka .NET, jako jsou třídy, vlastnosti a metody, a způsob, jakým by kompilátor nebo integrované vývojové prostředí měly tyto konvence vynucovat. Můžete například určit, že veřejný člen, který není velkými písmeny, by měl být považován za chybu kompilátoru nebo že pokud soukromé pole nezačíná _na , mělo by se vystavit upozornění sestavení.

Konkrétně můžete definovat pravidlo pojmenování, které se skládá ze tří částí:

  • Skupina symbolů, na kterou se pravidlo vztahuje, například na veřejné členy nebo soukromá pole.
  • Styl pojmenování, který se má přidružit k pravidlu, například že název musí být velkými písmeny nebo musí začínat podtržítkem.
  • Úroveň závažnosti zprávy, pokud prvky kódu zahrnuté ve skupině symbolů nedodržují styl pojmenování.

Obecná syntaxe

Pokud chcete definovat některou z výše uvedených entit – pravidlo pojmenování, skupinu symbolů nebo styl pojmenování – nastavte jednu nebo více vlastností pomocí následující syntaxe:

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

Všechna nastavení vlastností pro danou kind entitu a entityName tvoří danou definici entity.

Každá vlastnost by měla být nastavena pouze jednou, ale některá nastavení umožňují více hodnot oddělených čárkami.

Pořadí vlastností není důležité.

<kind> values

<Druh> určuje, který druh entity se definuje – pravidlo pojmenování, skupina symbolů nebo styl pojmenování – a musí to být jedna z těchto věcí:

Nastavení vlastnosti pro <Použití hodnoty typu> Příklad
Pravidlo pojmenování dotnet_naming_rule dotnet_naming_rule.types_should_be_pascal_case.severity = suggestion
Skupina symbolů dotnet_naming_symbols dotnet_naming_symbols.interface.applicable_kinds = interface
Styl pojmenování dotnet_naming_style dotnet_naming_style.pascal_case.capitalization = pascal_case

<entityName>

<entityName> je popisný název, který zvolíte, který přidruží nastavení více vlastností k jedné definici. Například následující vlastnosti vytvoří dvě definice skupiny symbolů interface a typeskaždý z nich má dvě vlastnosti nastavené na něm.

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

Každý druh entity – pravidlo pojmenování, skupina symbolů nebo styl pojmenování – má své vlastní podporované vlastnosti, jak je popsáno v následujících částech.

Vlastnosti skupiny symbolů

Pro skupiny symbolů můžete nastavit následující vlastnosti, abyste omezili, které symboly jsou součástí skupiny. Chcete-li zadat více hodnot pro jednu vlastnost, oddělte hodnoty čárkou.

Vlastnost Popis Povolené hodnoty Vyžadováno
applicable_kinds Druhy symbolů ve skupině 1 * (tuto hodnotu použijte k určení všech symbolů)
namespace
class
struct
interface
enum
property
method
field
event
delegate
parameter
type_parameter
local
local_function		 Ano
applicable_accessibilities Úrovně přístupnosti symbolů ve skupině * (tuto hodnotu použijte k určení všech úrovní přístupnosti.
public
internal nebo friend
private
protected
protected_internal nebo protected_friend
private_protected
local (pro symboly definované v rámci metody)		 Ano
required_modifiers Shoda pouze se symboly se všemi zadanými modifikátory 2 abstract nebo must_inherit
async
const
readonly
static nebo shared3		 Číslo

Poznámky:

  1. Členové řazené kolekce členů nejsou v současné době podporováni applicable_kinds.
  2. Skupina symbolů odpovídá všem modifikátorům required_modifiers ve vlastnosti. Pokud tuto vlastnost vynecháte, nejsou pro shodu vyžadovány žádné konkrétní modifikátory. To znamená, že modifikátory symbolu nemají žádný vliv na to, jestli se toto pravidlo použije nebo ne.
  3. Pokud vaše skupina obsahuje nebo obsahuje vlastnost, bude skupina obsahovat const také symboly, protože jsou implicitně/staticShared .required_modifierssharedstatic Pokud ale nechcete static , aby pravidlo pojmenování platilo pro const symboly, můžete vytvořit nové pravidlo pojmenování se skupinou symbolů const. Nové pravidlo bude mít přednost podle pořadí pravidel.
  4. class obsahuje záznamy jazyka C#.

Vlastnosti stylu pojmenování

Styl pojmenování definuje konvence, které chcete vynutit s pravidlem. Příklad:

  • Velká písmena s velkým písmenem PascalCase
  • Začíná na m_
  • Končí na _g
  • Oddělte slova pomocí __

Pro styl pojmenování můžete nastavit následující vlastnosti:

Vlastnost Popis Povolené hodnoty Vyžadováno
capitalization Styl psaní velkých písmen u slov v symbolu pascal_case
camel_case
first_word_upper
all_upper
all_lower		 Ano1
required_prefix Musí začínat těmito znaky. Číslo
required_suffix Musí končit těmito znaky. Číslo
word_separator Slova v symbolu musí být oddělena tímto znakem. Číslo

Poznámky:

  1. Styl psaní velkých písmen musíte zadat jako součást stylu pojmenování, jinak se styl pojmenování může ignorovat.

Vlastnosti pravidla pojmenování

Aby se pravidlo projevilo, vyžadují se všechny vlastnosti pravidla pojmenování.

Vlastnost Popis
symbols Název skupiny symbolů definované jinde; Pravidlo pojmenování se použije na symboly v této skupině.
style Název stylu pojmenování, který by měl být přidružen k tomuto pravidlu; styl je definován jinde.
severity Nastaví závažnost, se kterou se má vynucovat pravidlo pojmenování. Nastavte přidruženou hodnotu na jednu z dostupných úrovní závažnosti.1

Poznámky:

  1. Specifikace závažnosti v rámci pravidla pojmenování se respektuje pouze v rámci vývojových vývojových prostředí, jako je Například Visual Studio. Toto nastavení nepochopeno kompilátory jazyka C# nebo VB, proto se během sestavování nerespektuje. Pokud chcete vynutit pravidla stylu pojmenování při sestavení, měli byste místo toho nastavit závažnost pomocí konfigurace závažnosti pravidla kódu. Další informace najdete u tohoto problému na GitHubu.

Pořadí pravidel

Pořadí, ve kterém jsou pravidla pojmenování definována v souboru EditorConfig, nezáleží. Pravidla pojmenování se automaticky řadí podle definic samotných pravidel. Konkrétnější pravidla týkající se pravděpodobností přístupu, modifikátorů a symbolů mají přednost před méně specifickými pravidly. Pokud se pravidla překrývají nebo pokud řazení pravidel způsobuje problémy, můžete průnik těchto dvou pravidel rozdělit do nového pravidla, které má přednost před širšími pravidly, ze kterých bylo odvozeno. Příklady viz Příklad: Překrývající se strategie pojmenování a Příklad: const modifikátor zahrnuje static a readonly.

Rozšíření EditorConfig Language Service může analyzovat soubor EditorConfig a případy sestavy, kdy se pořadí pravidel v souboru liší od toho, co kompilátor použije za běhu.

Poznámka

Pokud používáte verzi sady Visual Studio starší než Visual Studio 2019, měla by se pravidla pojmenování řadit od většiny specifických po nejméně konkrétní v souboru EditorConfig. První pravidlo, které lze použít, je jediné použité pravidlo. Pokud však existuje více vlastností pravidla se stejným názvem, má přednost vlastnost naposledy nalezená s tímto názvem. Další informace najdete v tématu Hierarchie souborů a priorita.

Příklad: Překrývající se strategie pojmenování

Zvažte následující dvě pravidla pojmenování:

  1. Veřejné metody jsou PascalCase.
  2. Asynchronní metody končí na "Async".

U public async metod není zřejmé, které pravidlo má přednost. Můžete vytvořit nové pravidlo pro public async metody a přesně určit pojmenování.

Příklad: const modifikátor zahrnuje static a readonly

Zvažte následující dvě pravidla pojmenování:

  1. Konstantní pole jsou PascalCase.
  2. Neveřejná static pole jsou s_camelCase.

Pravidlo 2 je konkrétnější a má přednost, takže všechna neveřejná konstantní pole jsou s_camelCase. Pokud chcete tento problém vyřešit, můžete definovat pravidlo průniku: neveřejná konstantní pole jsou PascalCase.

Výchozí styly pojmenování

Pokud nezadáte žádná vlastní pravidla pojmenování, použijí se následující výchozí styly:

  • Pro třídy, struktury, výčty, vlastnosti, metody a události s libovolnou přístupností je výchozí styl pojmenování pascal případ.

  • Pro rozhraní s jakoukoli přístupností je výchozím stylem pojmenování pascal případ s požadovanou předponou I.

ID pravidla kódu: IDE1006 (Naming rule violation)

Všechny možnosti pojmenování mají ID IDE1006 pravidla a název Naming rule violation. Závažnost porušení názvů můžete nakonfigurovat globálně v souboru EditorConfig s následující syntaxí:

dotnet_diagnostic.IDE1006.severity = <severity value>

Hodnota závažnosti musí být warning nebo musí být vynucena při sestaveníerror. Všechny možné hodnoty závažnosti najdete na úrovni závažnosti.

Příklad: Velká písmena veřejného člena

Následující soubor .editorconfig obsahuje konvenci pojmenování, která určuje, že veřejné vlastnosti, metody, pole, události a delegáty, které jsou označeny readonly , musí být velkými písmeny. Tato konvence vytváření názvů určuje více druhů symbolů, na které se má pravidlo použít, a to pomocí čárky k oddělení hodnot.

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

Příklad: Pole privátní instance s podtržítkem

Tento fragment kódu souboru .editorconfig vynucuje, aby pole privátní instance měla začínat _hodnotou ; pokud tato konvence není dodržena, integrované vývojové prostředí (IDE) s ním bude zacházet jako s chybou kompilátoru. Privátní statická pole se ignorují.

Protože můžete definovat pouze skupinu symbolů na základě identifikátorů, static které má (například nebo readonly), a ne identifikátory, které nemá (například pole instance, protože staticneobsahuje), musíte definovat dvě pravidla pojmenování:

  1. Všechna soukromá pole ( static nebo ne) by měla mít underscored použitý styl pojmenování jako kompilátor error.
  2. U soukromých polí static by měl být underscored použit styl pojmenování s úrovní nonezávažnosti ; jinými slovy tento případ ignorujte.
[*.{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

Tento příklad také ukazuje, že definice entit lze znovu použít. Styl underscored pojmenování se používá jak v pravidlech private_fields_underscoredprivate_static_fields_none pojmenování, tak i v pravidlech pojmenování.

Viz také