Progettazione dei parametri

Annotazioni

Questo contenuto viene ristampato con il permesso di Pearson Education, Inc. da Framework Design Guidelines: Conventions, Idioms e Pattern per Librerie .NET Riutilizzabili, 2a Edizione. Tale edizione è stata pubblicata nel 2008 e il libro è stato completamente rivisto nella terza edizione. Alcune informazioni in questa pagina potrebbero non essere aggiornate.

Questa sezione fornisce linee guida generali sulla progettazione dei parametri, incluse le sezioni con linee guida per il controllo degli argomenti. Inoltre, è necessario fare riferimento alle linee guida descritte in Parametri di denominazione.

✔️ USARE il tipo di parametro meno derivato che fornisce la funzionalità richiesta dal membro.

Si supponga, ad esempio, di voler progettare un metodo che enumera una raccolta e stampa ogni elemento nella console. Un metodo di questo tipo deve accettare IEnumerable come parametro, non ArrayList o IList, ad esempio.

❌ NON usare parametri riservati.

Se in una versione futura è necessario fornire più parametri a un membro, si può aggiungere un nuovo overload.

❌ NON hanno metodi esposti pubblicamente che accettano puntatori, matrici di puntatori o matrici multidimensionali come parametri.

I puntatori e le matrici multidimensionali sono relativamente difficili da usare correttamente. In quasi tutti i casi, è possibile riprogettare le API per evitare di accettare questi tipi come parametri.

✔️ POSIZIONARE tutti i parametri out seguendo tutti i parametri passati per valore ref (escluse le matrici di parametri), anche se ciò comporta un'incoerenza nell'ordinamento dei parametri tra i sovraccarichi (consultare Sovraccarico dei membri).

I out parametri possono essere visualizzati come valori restituiti aggiuntivi e raggrupparli insieme semplificano la comprensione della firma del metodo.

✔️ Siate coerenti nella denominazione dei parametri durante la sovrascrittura dei membri o l'implementazione dei membri dell'interfaccia.

Ciò consente di comunicare meglio la relazione tra i metodi.

Scelta tra enumerazione e parametri booleani

✔️ DO usa enumerazioni se un membro avrebbe altrimenti due o più parametri booleani.

❌ NON usare valori booleani, a meno che non si sia assolutamente sicuri che non ci sarà mai bisogno di più di due valori.

Le enumerazioni offrono spazio per l'aggiunta futura di valori, ma è necessario essere consapevoli di tutte le implicazioni dell'aggiunta di valori alle enumerazioni, descritte in Enum Design.

✔️ PRENDERE IN CONSIDERAZIONE l'uso di valori booleani per i parametri del costruttore che sono realmente valori a due stati e vengono semplicemente usati per inizializzare le proprietà booleane.

Convalida degli argomenti

✔️ Convalida gli argomenti passati ai membri pubblici, protetti o implementati in modo esplicito. Lanciare System.ArgumentException, o una delle sue sottoclassi, se la convalida non riesce.

Si noti che la convalida effettiva non deve necessariamente verificarsi nel membro pubblico o protetto stesso. Potrebbe verificarsi a un livello inferiore in una routine privata o interna. Il punto principale è che l'intera superficie esposta agli utenti finali controlla gli argomenti.

✔️ Generare un'eccezione ArgumentNullException se viene passato un argomento null e il membro non supporta argomenti null.

✔️ Convalidare i parametri di enumerazione.

Non presumere che gli argomenti enum siano inclusi nell'intervallo definito dall'enum. CLR consente di eseguire il cast di qualsiasi valore intero in un valore di enumerazione, anche se il valore non è definito nell'enumerazione.

❌ NON usare Enum.IsDefined per i controlli dell'intervallo di enumerazione.

✔️ Tenere presente che gli argomenti modificabili potrebbero essere stati modificati dopo la convalida.

Se il membro è sensibile alla sicurezza, è consigliabile creare una copia e quindi convalidare ed elaborare l'argomento.

Passaggio di parametri

Dal punto di vista di un progettista di framework, ci sono tre gruppi principali di parametri: parametri per valore, ref parametri e out parametri.

Quando un argomento viene passato tramite un parametro per valore, il membro riceve una copia dell'argomento effettivo passato. Se l'argomento è un tipo valore, viene inserita una copia dell'argomento nello stack. Se l'argomento è un tipo riferimento, viene inserita una copia del riferimento nello stack. I linguaggi CLR più diffusi, ad esempio C#, VB.NET e C++, per impostazione predefinita passano parametri per valore.

Quando un argomento viene passato tramite un ref parametro, il membro riceve un riferimento all'argomento effettivo passato. Se l'argomento è un tipo valore, viene inserito un riferimento all'argomento nello stack. Se l'argomento è un tipo riferimento, viene inserito nello stack un riferimento al riferimento. Ref I parametri possono essere utilizzati per consentire al membro di modificare gli argomenti passati dal chiamante.

Out i parametri sono simili ai ref parametri, con alcune piccole differenze. Il parametro è inizialmente considerato non assegnato e non può essere letto nella definizione del membro prima che gli venga assegnato un valore. Inoltre, è necessario assegnare un valore al parametro prima che il membro restituisca un risultato.

❌ EVITARE l'uso dei parametri out o ref.

L'uso di out o ref parametri richiede esperienza con i puntatori, la comprensione di come i tipi di valore e i tipi di riferimento differiscono, e la gestione di metodi con più valori restituiti è richiesta. Inoltre, la differenza tra i parametri out e ref non è ampiamente comprensibile. Gli architetti del framework che progettano per un pubblico generale non devono aspettarsi che gli utenti diventino esperti nell'uso di parametri out, o ref.

❌ NON passare i tipi di riferimento per riferimento.

Esistono alcune eccezioni limitate alla regola, ad esempio un metodo che può essere usato per scambiare i riferimenti.

Membri con numero variabile di parametri

I membri che possono accettare un numero variabile di argomenti vengono espressi fornendo un parametro di matrice. Ad esempio, String fornisce il metodo seguente:

public class String {
    public static string Format(string format, object[] parameters);
}

Un utente può quindi chiamare il String.Format metodo , come indicato di seguito:

String.Format("File {0} not found in {1}",new object[]{filename,directory});

L'aggiunta della parola chiave params C# a un parametro di matrice modifica il parametro in un parametro di matrice cosiddetto params e fornisce un collegamento alla creazione di una matrice temporanea.

public class String {
    public static string Format(string format, params object[] parameters);
}

In questo modo l'utente può chiamare il metodo passando gli elementi della matrice direttamente nell'elenco di argomenti.

String.Format("File {0} not found in {1}",filename,directory);

Si noti che la parola chiave params può essere aggiunta solo all'ultimo parametro nell'elenco di parametri.

✔️ È consigliabile aggiungere la parola chiave params ai parametri della matrice se si prevede che gli utenti finali passino matrici con un numero ridotto di elementi. Se si prevede che molti elementi vengano passati in scenari comuni, gli utenti probabilmente non passeranno comunque questi elementi inline e quindi la parola chiave params non è necessaria.

❌ EVITARE di usare matrici params se il chiamante avrà quasi sempre l'input già in una matrice.

Ad esempio, i membri con parametri di matrice di byte non verrebbero quasi mai chiamati passando singoli byte. Per questo motivo, i parametri della matrice di byte in .NET Framework non usano la parola chiave params.

❌ NON utilizzare gli array di parametri se l'array viene modificato dal membro che accetta il parametro array di parametri.

Poiché molti compilatori trasformano gli argomenti delle funzioni membro in una matrice temporanea nel punto di chiamata, la matrice potrebbe essere un oggetto temporaneo e quindi eventuali modifiche alla matrice vengono perse.

✔️ PRENDERE IN CONSIDERAZIONE l'uso della parola chiave params in un overload semplice, anche se un overload più complesso non potrebbe utilizzarlo.

Chiediti se gli utenti apprezzerebbero avere la matrice params in un overload anche se non fosse in tutti gli overload.

✔️ PROVARE a ordinare i parametri per consentire l'uso della parola chiave params.

✔️ Considera di fornire sovraccarichi e percorsi del codice speciali per le chiamate con un piccolo numero di argomenti in API estremamente sensibili alle prestazioni.

In questo modo è possibile evitare di creare oggetti matrice quando l'API viene chiamata con un numero ridotto di argomenti. Formare i nomi dei parametri prendendo una forma singolare del parametro di matrice e aggiungendo un suffisso numerico.

È consigliabile eseguire questa operazione solo se si intende in modo speciale l'intero percorso del codice, non solo creare una matrice e chiamare il metodo più generale.

✔️ Fai attenzione al fatto che potrebbe essere passato un valore nullo come argomento del parametro array.

È necessario verificare che la matrice non sia Null prima dell'elaborazione.

❌ NON usare i varargs metodi, anche noti come puntini di sospensione.

Alcuni linguaggi CLR, ad esempio C++, supportano una convenzione alternativa per passare elenchi di parametri delle variabili denominati varargs metodi. La convenzione non deve essere usata nei framework, perché non è conforme a CLS.

Parametri del puntatore

In generale, i puntatori non devono essere visualizzati nella superficie pubblica di un framework di codice gestito ben progettato. Nella maggior parte dei casi, i puntatori devono essere incapsulati. Tuttavia, in alcuni casi i puntatori sono necessari per motivi di interoperabilità e l'uso di puntatori in tali casi è appropriato.

✔️ Assicurati di fornire un'alternativa per qualsiasi membro che accetta un argomento puntatore, in quanto i puntatori non sono conformi a CLS.

❌ EVITARE di eseguire un costoso controllo degli argomenti del puntatore.

✔️ DO seguire le convenzioni comuni relative ai puntatori durante la progettazione di membri che utilizzano puntatori.

Ad esempio, non è necessario passare l'indice iniziale, perché è possibile utilizzare una semplice aritmetica dei puntatori per ottenere lo stesso risultato.

Ristampato dall'autorizzazione di Pearson Education, Inc. da Framework Design Guidelines: Conventions, Idioms e Patterns for Reusable .NET Libraries, 2nd Edition di Krzysztof Cwalina e Brad Abrams, pubblicato il 22 ottobre 2008 da Addison-Wesley Professional come parte della Serie di sviluppo di Microsoft Windows.

Vedere anche

Last updated on 2025-06-17

Condividi tramite