Regole di denominazione in stile codice
Nel file con estensione editorconfig è possibile definire convenzioni di denominazione per gli elementi del codice del linguaggio di programmazione .NET, ad esempio classi, proprietà e metodi, e il modo in cui il compilatore o l'IDE deve applicare tali convenzioni. Ad esempio, è possibile specificare che un membro pubblico che non è in maiuscolo deve essere considerato come un errore del compilatore o che se un campo privato non inizia con , _
deve essere generato un avviso di compilazione.
In particolare, è possibile definire una regola di denominazione costituita da tre parti:
- Gruppo di simboli a cui si applica la regola, ad esempio membri pubblici o campi privati.
- Stile di denominazione da associare alla regola, ad esempio, che il nome deve essere maiuscolo o iniziare con un carattere di sottolineatura.
- Il livello di gravità del messaggio quando gli elementi di codice inclusi nel gruppo di simboli non seguono lo stile di denominazione.
Sintassi generale
Per definire una delle entità precedenti, ovvero una regola di denominazione, un gruppo di simboli o uno stile di denominazione, impostare una o più proprietà usando la sintassi seguente:
<kind>.<entityName>.<propertyName> = <propertyValue>
Tutte le impostazioni delle proprietà per un determinato kind
oggetto e entityName
costituiscono tale definizione di entità specifica.
Ogni proprietà deve essere impostata una sola volta, ma alcune impostazioni consentono più valori delimitati da virgole.
L'ordine delle proprietà non è importante.
<tipi> di valori
<kind> specifica il tipo di entità da definire, ovvero regola di denominazione, gruppo di simboli o stile di denominazione, e deve essere uno dei seguenti:
Per impostare una proprietà per | Usare il <valore del tipo> | Esempio |
---|---|---|
Regola di denominazione | dotnet_naming_rule |
dotnet_naming_rule.types_should_be_pascal_case.severity = suggestion |
Gruppo di simboli | dotnet_naming_symbols |
dotnet_naming_symbols.interface.applicable_kinds = interface |
Stile di denominazione | dotnet_naming_style |
dotnet_naming_style.pascal_case.capitalization = pascal_case |
<entityName>
<entityName> è un nome descrittivo scelto che associa più impostazioni di proprietà a una singola definizione. Ad esempio, le proprietà seguenti producono due definizioni interface
di gruppo di simboli e types
, ognuna delle quali ha due proprietà impostate su di essa.
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> e <propertyValue>
Ogni tipo di entità, ovvero regola di denominazione, gruppo di simboli o stile di denominazione, ha le proprie proprietà supportate, come descritto nelle sezioni seguenti.
Proprietà del gruppo di simboli
È possibile impostare le proprietà seguenti per i gruppi di simboli per limitare i simboli inclusi nel gruppo. Per specificare più valori per una singola proprietà, separare i valori con una virgola.
Proprietà | Descrizione | Valori consentiti | Richiesto |
---|---|---|---|
applicable_kinds |
Tipi di simboli nel gruppo 1 | * (usare questo valore per specificare tutti i simboli)namespace class struct interface enum property method field event delegate parameter type_parameter local local_function |
Sì |
applicable_accessibilities |
Livelli di accessibilità dei simboli nel gruppo | * (usare questo valore per specificare tutti i livelli di accessibilità)public internal oppure friend private protected protected_internal oppure protected_friend private_protected local (per i simboli definiti all'interno di un metodo) |
Sì |
required_modifiers |
Solo simboli di corrispondenza con tutti i modificatori specificati 2 | abstract oppure must_inherit async const readonly static o shared 3 |
No |
Note:
- I membri della tupla non sono attualmente supportati in
applicable_kinds
. - Il gruppo di simboli corrisponde a tutti i modificatori nella
required_modifiers
proprietà . Se si omette questa proprietà, non sono necessari modificatori specifici per una corrispondenza. Ciò significa che i modificatori di un simbolo non hanno alcun effetto sull'applicazione di questa regola. - Se il gruppo ha o nella proprietà , il gruppo includerà
const
anche simboli perché sono implicitamente/static
Shared
.required_modifiers
shared
static
Tuttavia, se non si vuole che lastatic
regola di denominazione venga applicata aiconst
simboli, è possibile creare una nuova regola di denominazione con un gruppo di simboli diconst
. La nuova regola avrà la precedenza in base all'ordine delle regole. class
include record C#.
Proprietà dello stile di denominazione
Uno stile di denominazione definisce le convenzioni da applicare con la regola. Ad esempio:
- Usare maiuscole con
PascalCase
- Inizia con
m_
- Termina con
_g
- Separare le parole con
__
È possibile impostare le proprietà seguenti per uno stile di denominazione:
Proprietà | Descrizione | Valori consentiti | Richiesto |
---|---|---|---|
capitalization |
Stile di maiuscola per le parole all'interno del simbolo | pascal_case camel_case first_word_upper all_upper all_lower |
Sì1 |
required_prefix |
Deve iniziare con questi caratteri | No | |
required_suffix |
Deve terminare con questi caratteri | No | |
word_separator |
Le parole all'interno del simbolo devono essere separate con questo carattere | No |
Note:
- Nell'ambito dello stile di denominazione è necessario specificare uno stile per le lettere maiuscole e minuscole. In caso contrario, lo stile di denominazione potrebbe essere ignorato.
Proprietà delle regole di denominazione
Tutte le proprietà delle regole di denominazione sono necessarie per rendere effettiva una regola.
Proprietà | Descrizione |
---|---|
symbols |
Nome di un gruppo di simboli definito altrove; la regola di denominazione verrà applicata ai simboli in questo gruppo |
style |
Nome dello stile di denominazione che deve essere associato a questa regola; lo stile è definito altrove |
severity |
Imposta la gravità con cui applicare la regola di denominazione. Impostare il valore associato su uno dei livelli di gravità disponibili.1 |
Note:
- La specifica di gravità all'interno di una regola di denominazione viene rispettata solo all'interno degli IDE di sviluppo, ad esempio Visual Studio. Questa impostazione non è riconosciuta dai compilatori C# o VB, quindi non rispettata durante la compilazione. Per applicare regole di stile di denominazione per la compilazione, è necessario impostare invece la gravità usando la configurazione della gravità della regola del codice. Per altre informazioni, vedere questo problema in GitHub.
Ordine delle regole
L'ordine in cui le regole di denominazione sono definite in un file EditorConfig non è rilevante. Le regole di denominazione vengono ordinate automaticamente in base alle definizioni delle regole stesse. Regole più specifiche relative a accessibilità, modificatori e simboli hanno la precedenza su regole meno specifiche. Se si verifica una sovrapposizione tra regole o se l'ordinamento delle regole causa problemi, è possibile suddividere l'intersezione delle due regole in una nuova regola che ha la precedenza sulle regole più ampie da cui è stata derivata. Per esempi, vedere Esempio: Strategie di denominazione sovrapposte ed Esempio: const
modificatore include static
e readonly
.
L'estensione del servizio di linguaggio EditorConfig può analizzare un file EditorConfig e i casi in cui l'ordinamento delle regole nel file è diverso da quello che il compilatore userà in fase di esecuzione.
Nota
Se si usa una versione di Visual Studio precedente a Visual Studio 2019, le regole di denominazione devono essere ordinate dalla più specifica alla meno specifica nel file EditorConfig. La prima regola rilevata che può essere applicata è l'unica regola che viene applicata. Se tuttavia sono presenti più proprietà della regola con lo stesso nome, la proprietà con tale nome individuata più di recente ha la precedenza. Per altre informazioni, vedere Gerarchia e precedenza dei file.
Esempio: Strategie di denominazione sovrapposte
Considerare le due regole di denominazione seguenti:
- I metodi pubblici sono PascalCase.
- I metodi asincroni terminano con
"Async"
.
Per public async
i metodi, non è ovvio quale regola ha la precedenza. È possibile creare una nuova regola per public async
i metodi e specificare esattamente la denominazione.
Esempio: const
modificatore include static
e readonly
Considerare le due regole di denominazione seguenti:
- I campi costanti sono PascalCase.
- I campi non pubblici
static
sono s_camelCase.
La regola 2 è più specifica e ha la precedenza, quindi tutti i campi costanti non pubblici sono s_camelCase. Per risolvere il problema, è possibile definire una regola di intersezione: i campi costanti non pubblici sono PascalCase.
Stili di denominazione predefiniti
Se non si specificano regole di denominazione personalizzate, vengono usati gli stili predefiniti seguenti:
Per classi, struct, enumerazioni, proprietà, metodi ed eventi con qualsiasi accessibilità, lo stile di denominazione predefinito è Pascal.
Per le interfacce con qualsiasi accessibilità, lo stile di denominazione predefinito è pascal con un prefisso obbligatorio di I.
ID regola del codice: IDE1006 (Naming rule violation)
Tutte le opzioni di denominazione hanno ID IDE1006
regola e titolo Naming rule violation
. È possibile configurare la gravità delle violazioni di denominazione a livello globale in un file EditorConfig con la sintassi seguente:
dotnet_diagnostic.IDE1006.severity = <severity value>
Il valore di gravità deve essere warning
o error
essere applicato alla compilazione. Per tutti i possibili valori di gravità, vedere livello di gravità.
Esempio: Capitalizzazione dei membri pubblici
Il file con estensione editorconfig seguente contiene una convenzione di denominazione che specifica che le proprietà pubbliche, i metodi, i campi, gli eventi e i delegati contrassegnati readonly
devono essere contrassegnati in maiuscolo. Questa convenzione di denominazione specifica più tipi di simbolo a cui applicare la regola, usando una virgola per separare i valori.
[*.{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
Esempio: Campi dell'istanza privata con carattere di sottolineatura
Questo frammento di file con estensione editorconfig impone che i campi dell'istanza privata inizino con un _
; se tale convenzione non viene seguita, l'IDE lo considererà come un errore del compilatore. I campi statici privati vengono ignorati.
Poiché è possibile definire un gruppo di simboli solo in base agli identificatori di cui dispone (ad esempio, static
o readonly
) e non agli identificatori non ha (ad esempio, un campo di istanza perché non ha static
), è necessario definire due regole di denominazione:
- Tutti i campi privati,
static
o meno, devono avere lounderscored
stile di denominazione applicato come compilatoreerror
. - Ai campi privati con
static
deve essere applicato lounderscored
stile di denominazione con un livello di gravità dinone
. In altre parole, ignorare questo caso.
[*.{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
Questo esempio dimostra anche che le definizioni di entità possono essere riutilizzate. Lo underscored
stile di denominazione viene usato dalle private_fields_underscored
regole di denominazione e private_static_fields_none
.