Regole di denominazione in stile codice

  • Articolo

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

Note:

  1. I membri della tupla non sono attualmente supportati in applicable_kinds.
  2. 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.
  3. Se il gruppo ha o nella proprietà , il gruppo includerà const anche simboli perché sono implicitamente/staticShared .required_modifierssharedstatic Tuttavia, se non si vuole che la static regola di denominazione venga applicata ai const simboli, è possibile creare una nuova regola di denominazione con un gruppo di simboli di const. La nuova regola avrà la precedenza in base all'ordine delle regole.
  4. 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:

  1. 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:

  1. 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:

  1. I metodi pubblici sono PascalCase.
  2. 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:

  1. I campi costanti sono PascalCase.
  2. 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:

  1. Tutti i campi privati, static o meno, devono avere lo underscored stile di denominazione applicato come compilatore error.
  2. Ai campi privati con static deve essere applicato lo underscored stile di denominazione con un livello di gravità di none. 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 .

Vedi anche