Esistono buone tecniche o test per i tipi di denominazione?

Una domanda imbarazzante e aperta, ma è un problema a cui mi imbatto sempre:

Il software facile da gestire e da utilizzare è un software ben progettato. Cercare di rendere intuitivo un progetto significa nominare i componenti in modo tale che lo sviluppatore successivo sia in grado di inferire la funzione del componente. Questo è il motivo per cui non chiamiamo le nostre classi "Tipo1", "Tipo2", ecc.

Quando si modella un concetto del mondo reale (ad es. Cliente), questo è generalmente semplice come nominare il proprio tipo dopo il concetto del mondo reale che viene modellato. Ma quando costruisci cose astratte, che sono più orientate al sistema, è molto facile rimanere senza nomi che siano sia facili da leggere che semplici da digerire.

Peggiora (per me) quando provo a nominare famiglie di tipi, con un tipo base o un'interfaccia che descrive cosa devono fare i componenti, ma non come funzionano. Ciò porta naturalmente a ogni tipo derivato che cerca di descrivere il sapore dell'implementazione (ad esempio IDataConnectione SqlConnectionin .NET Framework), ma come si esprime qualcosa di complicato come "funziona riflettendo e cercando un insieme specifico di attributi"?

Quindi, quando hai finalmente scelto un nome per il tipo che ritieni descriva cosa sta cercando di fare, il tuo collega chiede "WTF fa DomainSecurityMetadataProviderdavvero questo ? "

Esistono buone tecniche per scegliere un nome ben intenzionato per un componente o come costruire una famiglia di componenti senza ottenere nomi confusi?

Esistono dei semplici test che posso applicare a un nome per capire meglio se il nome è "buono" e dovrebbe essere più intuitivo per gli altri?

Per la denominazione, ci sono sei tecniche che hanno dimostrato di funzionare per me:

1. passare molto tempo a inventare nomi
2. utilizzare le recensioni del codice
3. non esitate a rinominare
4. passare molto tempo a inventare nomi
5. utilizzare le recensioni del codice
6. non esitate a rinominare

PS. Nel caso in cui la tua API sia pubblica, sopra si applica prima di ciò, perché, sai,

"Le API pubbliche, come i diamanti, sono per sempre. Hai una possibilità di farlo nel modo giusto, quindi dai il meglio di te ..." (Joshua Bloch, How to Design a Good API e Why it Matters )

Il mio test di base è se puoi descrivere la funzione della variabile usando solo parole della variabile:

ad es. se DomainSecurityMetadataProvider o "Fornisce metadati di sicurezza del dominio" o "Fornisce metadati relativi alla sicurezza del dominio", va bene.

Tuttavia, ci sono sfumature che variano da persona a persona:

ad esempio, per me original_team_code è il codice per la squadra originale, mentre per qualcun altro potrebbe essere il codice originale per la squadra. Uno dei miei preferiti era uno "UnsafeLegacyMutex", che non potevo fare a meno di leggere come "Questo è un Mutex legacy che non è sicuro", piuttosto che "Questo è un Mutex per il codice legacy ThreadUnsafe".

Quindi il mio test esteso è quello di scrivere la variabile su una board / wiki / chat e indurre le persone a indovinare cosa significhi.

Esistono buone tecniche per scegliere un nome ben intenzionato per un componente o come costruire una famiglia di componenti senza ottenere nomi confusi?

Non proprio.

Un consiglio, tuttavia, è quello di evitare la "voce passiva".

"DomainSecurityMetadataProvider" è passivo. Non c'è nessun verbo, sono tutti nomi e nomi usati come aggettivi.

"ProvideMetadataForDomainSecurity" è più attivo. C'è un verbo

La programmazione orientata agli oggetti è tutto (davvero) sostantivo-verbo. Noun == oggetto. Metodo verbo ==. Quindi un nome di classe è generalmente molto "sostantivo". Rompere questa abitudine e iniziare a inserire i verbi è difficile.

Esistono dei semplici test che posso applicare a un nome per capire meglio se il nome è "buono" e dovrebbe essere più intuitivo per gli altri?

Sì. Hai definito un test eccellente nella tua domanda. Chiedi ad altre persone.

Ai vecchi tempi lo chiamavamo "design walkthrough". Era un grande affare sudato in una metodologia a cascata. Oggi, con i metodi Agile, dovrebbe essere una normale collaborazione tra l'autore e gli utenti di una classe. Non (e non dovrebbe) impiegare molto tempo. Discutere del design (e dei nomi) prima di scrivere i test (e il codice) ridurrà il fattore stupore e può prevenire i WTF.

Usando un thesaurus

Molto spesso mi riferirò a un thesaurus quando farò un nuovo sviluppo al fine di trovare parole appropriate per descrivere le mie classi e metodi.

Classi che contengono principalmente la logica di funzionamento

Tendo a nominare classi che forniscono principalmente metodi operativi in ​​una struttura sostantivo-verbo come "EntityProvider", "EntityLocator", ecc.

Queste classi generalmente non contengono molto stato.

Classi che contengono stato

Le schermate dell'interfaccia utente e le entità dei dati sono generalmente stateful, e quindi ho semplicemente dato un nome a queste classi con un modello di sostantivo o aggettivo-sostantivo.

Esempi: Persona, Dipendente, Impiegato attuale, Ex dipendente

Classi di utilità

Le classi che contengono solo metodi statici sono generalmente considerate classi "utility", quindi le chiamo costantemente con un suffisso "Utility".

Esempi: NetworkUtilities, FileUtilities

test

Non ho buoni test per decidere se qualcosa è scarsamente chiamato, ma suggerirei di provare a usare un singolo nome e / o un singolo verbo nel nome, quindi pensa se quel nome / verbo descrive accuratamente ciò che rinominare.

Se ritieni che ci sia qualcosa di più nella classe / metodo che non sia catturato dal nome, potrebbe essere necessario riformattare quella classe / metodo.

Alan Green e Jeff Attwood hanno scritto sui mali delle classi di denominazione con il suffisso "Manager". Sostengono che il termine "Manager" è abusato ed è troppo vago per trasmettere qualcosa di significativo. Devo essere d'accordo

L'articolo di Jeff fornisce anche un elenco di linee guida suggerite dal Codice completo di Steve McConnell.

variabili

Recentemente ho sperimentato nomi di variabili / parametri descrittivi più lunghi che incorporano preposizioni, come "Of", "By", "For", ecc. Alcuni esempi sono mostrati di seguito:

string firstNameOfEmployee;

string lastNameOfEmployee;

// here I nimbly avoid worrying about whether to call it "Id" or "ID" :)
int idOfEmployee;

decimal amountForDeposit;

Account accountForDeposit;

Trovo che funzioni perfettamente con la funzionalità intellisense di Visual Studio che semplifica la digitazione di questi nomi lunghi. Trovo anche che ci sia meno duplicazione dei prefissi dei nomi delle variabili (ad esempio personID, personFirstName, personLastName vs. idOfPerson, firstNameOfPerson, lastNameOfPerson), fornendo un "hash" migliore che rende ancora più utile l'intellisense.

Quindi, quando hai finalmente scelto un nome per il tipo che ritieni descriva cosa sta cercando di fare, il tuo collega chiede "WTF fa davvero DomainSecurityMetadataProvider?"

Che tipo di nome ti aspetti per una classe complessa e specifica del dominio? Questo è buono come andrà a finire senza rendere il nome della tua classe una frase (che farà pensare a tutti che hai dato troppa responsabilità a una singola classe)

Vorrei prendere in considerazione la rinuncia al provider dal nome. Se menziona specificamente i metadati, tutti sanno già che stai usando la riflessione. Potresti rendere una parola più concisa (o eventualmente cambiare in un'altra parola: è più un consumatore che un fornitore da quello che hai scritto)

Usa le metafore per descrivere parti del sistema. Non solo ti farà scoprire nuove analogie, ma ti aiuterà a nominare più facilmente.

(Sono consapevole che questo non è un esempio forte ma comunque) Ad esempio puoi chiamare una variabile o un tipo as mailbox, che funge da coda per i messaggi ricevuti per una classe.

Una cosa su cui sarei molto sicuro è che ai nomi non dovrebbe mai essere permesso di essere errati. Il miglior esempio, durante alcuni re-factoring, molto codice è cambiato e alcune variabili hanno iniziato a riferirsi a qualcosa di diverso da quello che suggerivano i loro nomi.

Molto presto, un programmatore stava spendendo anni e usando alcune chiamate al database molto costose, cercando di ottenere alcuni pezzi di dati che erano già stati estratti e archiviati. Ho rinominato tutto e all'improvviso abbiamo potuto rimuovere una tonnellata di logica complicata e piena di errori.

Spero che i casi in cui devi pensare così tanto ai nomi siano rari. Quando si presentano questi casi, basta scrivere un paragrafo che spieghi cosa fa la classe. Contrariamente ai commenti in-funzione o ai commenti a livello di funzione, lo scopo principale di una classe cambia raramente, quindi il rischio che i commenti scadano è relativamente piccolo. Quindi hai il lusso di scrivere un paio di paragrafi o persino disegnare ASCII per spiegare cosa fa la classe.