Delen via

Naamgevingsregels in codestijl

  • Artikel

In het .editorconfig-bestand kunt u naamconventies definiëren voor code-elementen van uw .NET-programmeertaal, zoals klassen, eigenschappen en methoden, en hoe de compiler of IDE deze conventies moet afdwingen. U kunt bijvoorbeeld opgeven dat een openbaar lid dat niet in hoofdletters is geplaatst, moet worden behandeld als een compilerfout of dat als een privéveld niet begint met een _buildwaarschuwing moet worden uitgegeven.

U kunt met name een naamgevingsregel definiëren, die uit drie delen bestaat:

  • De symboolgroep waarop de regel van toepassing is, bijvoorbeeld op openbare leden of privévelden.
  • De naamgevingsstijl die u aan de regel wilt koppelen, bijvoorbeeld dat de naam een hoofdletter moet hebben of moet beginnen met een onderstrepingsteken.
  • Het ernstniveau van het bericht wanneer code-elementen in de symboolgroep niet de naamgevingsstijl volgen.

Algemene syntaxis

Als u een van de bovenstaande entiteiten wilt definiëren( een naamgevingsregel, symboolgroep of naamgevingsstijl), stelt u een of meer eigenschappen in met behulp van de volgende syntaxis:

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

Alle eigenschapsinstellingen voor een bepaalde kind en entityName vormen de definitie van die specifieke entiteit.

Elke eigenschap mag slechts eenmaal worden ingesteld, maar sommige instellingen staan meerdere door komma's gescheiden waarden toe.

De volgorde van de eigenschappen is niet belangrijk.

<soort> waarden

<Type> geeft aan welk type entiteit wordt gedefinieerd: naamgevingsregel, symboolgroep of naamgevingsstijl en moet een van de volgende zijn:

Een eigenschap instellen voor <De soortwaarde> gebruiken Opmerking
Naamgevingsregel dotnet_naming_rule dotnet_naming_rule.types_should_be_pascal_case.severity = suggestion
Symboolgroep dotnet_naming_symbols dotnet_naming_symbols.interface.applicable_kinds = interface
Naamgevingsstijl dotnet_naming_style dotnet_naming_style.pascal_case.capitalization = pascal_case

<entityName>

<entityName> is een beschrijvende naam die u kiest die meerdere eigenschapsinstellingen aan één definitie koppelt. Met de volgende eigenschappen worden bijvoorbeeld twee definities van symbolengroep geproduceerd, interface en typeselk met twee eigenschappen die erop zijn ingesteld.

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

Elk type entiteit( naamgevingsregel, symboolgroep of naamgevingsstijl) heeft eigen ondersteunde eigenschappen, zoals beschreven in de volgende secties.

Eigenschappen van symboolgroep

U kunt de volgende eigenschappen voor symboolgroepen instellen om te beperken welke symbolen in de groep zijn opgenomen. Als u meerdere waarden voor één eigenschap wilt opgeven, scheidt u de waarden met een komma.

Eigenschappen Beschrijving Toegestane waarden Vereist
applicable_kinds Soorten symbolen in de groep 1 * (gebruik deze waarde om alle symbolen op te geven)
namespace
class
struct
interface
enum
property
method
field
event
delegate
parameter
type_parameter
local
local_function		 Ja
applicable_accessibilities Toegankelijkheidsniveaus van de symbolen in de groep * (gebruik deze waarde om alle toegankelijkheidsniveaus op te geven)
public
internal of friend
private
protected
protected_internal of protected_friend
private_protected
local (voor symbolen die zijn gedefinieerd in een methode)		 Ja
required_modifiers Alleen symbolen vergelijken met alle opgegeven modifiers 2 abstract of must_inherit
async
const
readonly
static of shared 3		 Nee

Opmerkingen:

  1. Tuple-leden worden momenteel niet ondersteund in applicable_kinds.
  2. De symboolgroep komt overeen met alle modifiers in de required_modifiers eigenschap. Als u deze eigenschap weglaat, zijn er geen specifieke modifiers vereist voor een overeenkomst. Dit betekent dat de modifiers van een symbool geen effect hebben op het al dan niet toepassen van deze regel.
  3. Als uw groep de eigenschap heeft of bevat, bevat const de groep ook symbolen omdat ze impliciet/Sharedstatic zijn.required_modifiers shared static Als u echter niet wilt dat de static naamgevingsregel wordt toegepast op const symbolen, kunt u een nieuwe naamgevingsregel maken met een symboolgroep van const. De nieuwe regel heeft voorrang op basis van de regelvolgorde.
  4. class bevat C#-records.

Naamgevingsstijleigenschappen

Een naamgevingsstijl definieert de conventies die u wilt afdwingen met de regel. Voorbeeld:

  • Hoofdletters maken met PascalCase
  • Begint met m_
  • Eindigt met _g
  • Woorden scheiden met __

U kunt de volgende eigenschappen instellen voor een naamgevingsstijl:

Eigenschappen Beschrijving Toegestane waarden Vereist
capitalization Hoofdletterstijl voor woorden binnen het symbool pascal_case
camel_case
first_word_upper
all_upper
all_lower		 Ja1
required_prefix Moet beginnen met deze tekens Nee
required_suffix Moet eindigen met deze tekens Nee
word_separator Woorden binnen het symbool moeten worden gescheiden door dit teken Nee

Opmerkingen:

  1. U moet een hoofdletterstijl opgeven als onderdeel van uw naamgevingsstijl, anders wordt uw naamgevingsstijl mogelijk genegeerd.

Naamgevingsregeleigenschappen

Alle naamgevingsregeleigenschappen zijn vereist om een regel van kracht te laten worden.

Eigenschappen Beschrijving
symbols De naam van een symboolgroep die elders is gedefinieerd; de naamgevingsregel wordt toegepast op de symbolen in deze groep
style De naam van de naamgevingsstijl die moet worden gekoppeld aan deze regel; de stijl elders wordt gedefinieerd
severity Hiermee stelt u de ernst in waarmee de naamgevingsregel moet worden afgedwongen. Stel de bijbehorende waarde in op een van de beschikbare ernstniveaus.1

Opmerkingen:

  1. De ernstspecificatie binnen een naamgevingsregel wordt alleen gerespecteerd binnen ontwikkelings-ID's, zoals Visual Studio. Deze instelling wordt niet begrepen door de C#- of VB-compilers, dus niet gerespecteerd tijdens de build. Als u naamgevingsregels wilt afdwingen bij het bouwen, moet u in plaats daarvan de ernst instellen met behulp van de ernstconfiguratie van coderegels. Zie dit GitHub-probleem voor meer informatie.

Regelvolgorde

De volgorde waarin naamgevingsregels zijn gedefinieerd in een EditorConfig-bestand maakt niet uit. De naamgevingsregels worden automatisch geordend volgens de definities van de regels zelf. Meer specifieke regels met betrekking tot toegankelijkheid, modifiers en symbolen hebben voorrang op minder specifieke regels. Als er sprake is van overlapping tussen regels of als de regelvolgorde problemen veroorzaakt, kunt u het snijpunt van de twee regels opsplitsen in een nieuwe regel die voorrang heeft op de bredere regels waaruit deze is afgeleid. Zie Voorbeeld: Overlappende naamgevingsstrategieën en Voorbeeld: const modifier bevat static en readonly.

De editorConfig Language Service-extensie kan een EditorConfig-bestand en rapportcases analyseren waarbij de regelvolgorde in het bestand verschilt van wat de compiler tijdens runtime gaat gebruiken.

Notitie

Als u een versie van Visual Studio gebruikt die ouder is dan Visual Studio 2019, moeten naamgevingsregels worden geordend van meest specifiek naar minst specifiek in het EditorConfig-bestand. De eerste regel die kan worden toegepast, is de enige regel die wordt toegepast. Als er echter meerdere regeleigenschappen met dezelfde naam zijn, heeft de laatst gevonden eigenschap met die naam voorrang. Zie Bestandshiërarchie en prioriteit voor meer informatie.

Voorbeeld: Overlappende naamgevingsstrategieën

Houd rekening met de volgende twee naamgevingsregels:

  1. Openbare methoden zijn PascalCase.
  2. Asynchrone methoden eindigen met "Async".

Voor public async methoden is het niet duidelijk welke regel voorrang heeft. U kunt een nieuwe regel voor public async methoden maken en de naamgeving exact opgeven.

Voorbeeld: const modifier bevat static en readonly

Houd rekening met de volgende twee naamgevingsregels:

  1. Constante velden zijn PascalCase.
  2. Niet-openbare static velden worden s_camelCase.

Regel 2 is specifieker en heeft voorrang, dus alle niet-openbare constante velden worden s_camelCase. U kunt het probleem oplossen door een snijpuntregel te definiëren: niet-openbare constante velden zijn PascalCase.

Standaardnaamstijlen

Als u geen aangepaste naamgevingsregels opgeeft, worden de volgende standaardstijlen gebruikt:

  • Voor klassen, structs, opsommingen, eigenschappen, methoden en gebeurtenissen met elke toegankelijkheid is de standaardnaamgevingsstijl Pascal case.

  • Voor interfaces met elke toegankelijkheid is de standaardnaamgevingsstijl Pascal met een vereist voorvoegsel van I.

Coderegel-id: IDE1006 (Naming rule violation)

Alle naamgevingsopties hebben regel-id IDE1006 en titel Naming rule violation. U kunt de ernst van naamschendingen globaal configureren in een EditorConfig-bestand met de volgende syntaxis:

dotnet_diagnostic.IDE1006.severity = <severity value>

De ernstwaarde moet worden warning afgedwongen of error afgedwongen bij de build. Zie ernstniveau voor alle mogelijke ernstwaarden.

Voorbeeld: Hoofdlettergebruik van openbare leden

Het volgende .editorconfig-bestand bevat een naamconventie waarmee wordt aangegeven dat openbare eigenschappen, methoden, velden, gebeurtenissen en gemachtigden die zijn gemarkeerd readonly , een hoofdletter moeten hebben. Deze naamconventie specificeert meerdere soorten symbolen waarop de regel moet worden toegepast, met behulp van een komma om de waarden te scheiden.

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

Voorbeeld: Velden van een privé-exemplaar met onderstrepingsteken

Dit .editorconfig-bestandsfragment dwingt af dat velden van het privé-exemplaar moeten beginnen met een _; als die conventie niet wordt gevolgd, zal de IDE deze behandelen als een compilerfout. Privé statische velden worden genegeerd.

Omdat u alleen een symboolgroep kunt definiëren op basis van de id's die de groep heeft (bijvoorbeeld static of readonly), en niet door de id's die de groep niet heeft (bijvoorbeeld een exemplaarveld omdat deze niet beschikt static), moet u twee naamgevingsregels definiëren:

  1. Voor alle privévelden moet static de underscored naamgevingsstijl al dan niet als compiler errorworden toegepast.
  2. Voor privévelden met static moet de underscored naamgevingsstijl worden toegepast met een ernstniveau van none; met andere woorden, negeer dit geval.
[*.{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

In dit voorbeeld ziet u ook dat entiteitsdefinities opnieuw kunnen worden gebruikt. De underscored naamgevingsstijl wordt gebruikt door zowel de private_static_fields_none private_fields_underscored regels als naamgevingsregels.

Zie ook