Linee guida significative per la denominazione dei metodi concise

Naming. Una delle cose più difficili sullo sviluppo del software:)

Quando nomino qualcosa, ecco il mio insieme di priorità:

• Segui gli idiomi della mia lingua. A Ruby piacciono i sottolineature. A Javascript piace il caso dei cammelli. Qualunque sia la lingua in cui ti trovi è la convenzione da seguire.
• Rivela l'intento dell'API. Non è "send_http_data" è "post_twitter_status"
• Evita di divulgare i dettagli di implementazione. Dì, prefisso una variabile con un tipo.
• Non usa più caratteri del necessario senza infrangere le linee guida precedenti.

Ovviamente questo è un approccio piuttosto semplicistico. Il nome è sfumato.

Per ulteriori ricerche, ti consiglio di leggere L'arte del codice leggibile , in quanto fornisce alcuni eccellenti, succinti consigliare sulla denominazione del metodo. Per ulteriori ricerche non posso raccomandare più caldamente Codice pulito

La tentazione di codificare uno stile o una convenzione per la denominazione può, in alcuni casi, portare a abitudini oggi considerate di scarsa pratica, come ad esempio l'uso della notazione ungherese. La semplice risposta è quella di dimenticare la convenzione e lo stile di denominazione come se fosse una cosa separata da determinare separatamente, e invece di concentrarsi sull'assegnazione di nomi a tutto il sistema in base a ciò che rappresenta effettivamente. I nomi dei metodi saranno naturalmente concisi se limiti la funzionalità di ciascun metodo in modo che faccia una sola cosa in modo nozionale e se il nome del tuo metodo descriva effettivamente l'unica cosa che il metodo dovrebbe fare.

Variabili, campi, classi e nomi di file sono qualcos'altro. Suggerirei che se i nomi delle variabili stanno diventando troppo lunghi, allora stai cercando di descrivere questi elementi in un dettaglio troppo grande, o rappresentano qualcosa di complesso che dovrebbe essere suddiviso in parti più piccole, o forse descritto in modo più astratto modo.

Alla fine della giornata, vuoi evitare un brutto codice con nomi che occupano un'intera riga, o che sono così disinvolti da privarli del loro valore.

Per me, trovare un buon nome per qualcosa torna sempre a pensarlo come un oggetto che deve giustificare la sua esistenza. Chiediti:

• Che cosa fa la classe / metodo / variabile, cioè qual è il suo scopo più ampio e a cosa serve?
• Che cosa specificamente riguardo al suo scopo ha bisogno di comunicare, cioè qual è la parte essenziale che il nome deve avere in esso?

La maggior parte degli sviluppatori concorda sul fatto che la leggibilità è sempre di fondamentale importanza quando si parla di denominazione. Non scrivere semplicemente il codice in modo che tu sappia cosa intendi mentre lo stai scrivendo, scrivilo in modo che qualcuno che guarda il codice per la prima volta ad un certo punto del futuro sappia cosa vuoi dire senza dover pensare troppo. Scriverò il codice solo una volta, ma durante la sua durata molto probabilmente dovrà essere modificato molte volte e letto ancora più volte.

Il codice dovrebbe essere self-documenting , ovvero la tua denominazione dovrebbe rendere evidente ciò che fa qualcosa. Se devi spiegare che cosa fa una riga di codice in un commento e rinominare le cose non migliora abbastanza, dovresti seriamente considerare di refactoring quella linea in un nuovo metodo con un nome descrittivo appropriato, in modo che leggendo il metodo originale, il la nuova chiamata al metodo descrive cosa sta succedendo. Non aver paura di avere nomi lunghi; ovviamente non dovresti scrivere romanzi in classe / metodo / nomi di variabili, ma preferirei che un nome fosse troppo lungo e descrittivo che troppo corto e ho bisogno di capire cosa fa guardando sotto il cofano. Fatta eccezione per alcune ovvie eccezioni come le coordinate x / y e gli acronimi comunemente usati, evitare nomi e abbreviazioni di singoli caratteri. Chiamare qualcosa "bkBtn" invece di "backButton" potrebbe aver avuto uno scopo quando i nomi erano limitati a 8 caratteri ei dinosauri vagavano per la terra, ma in questi giorni con il completamento del codice non c'è davvero alcuna scusa per abbreviare.

Per quanto la tua lingua lo consenta, leggi il tuo codice come una frase inglese. Gli oggetti usano nomi, i metodi usano i verbi. I metodi booleani di solito iniziano con "è", ma ci sono molte altre opzioni che trasmettono il significato ancora meglio, a seconda del caso d'uso, come "può", "dovrebbe" o "fa". Naturalmente, non tutte le lingue possono essere valide come Smalltalk, ma alcuni simboli sono generalmente interpretati come parti della frase. Due convenzioni Smalltalk Personalmente mi piace prendere il più possibile in altri linguaggi, prefisso il nome dei parametri del ciclo con "each" e prefisso i parametri del metodo con l'articolo "a" (o "an", o "some" per le collezioni) . Questo potrebbe non essere uno standard comune in Java, e chiunque può ignorare questo bit, ma trovo che questo migliori notevolmente la leggibilità del codice. Ad esempio (esempio in Java):

public boolean shouldConsiderAbbreviating(List<String> someNames) {
  for (String eachName : someNames) {
    if (isTooLong(eachName)) {
      return true;
    }
  }
  return false;
}

Questo dovrebbe essere leggibile per le persone con un minimo di conoscenza di Java come qualcosa del genere:

Per determinare se dovresti prendere in considerazione l'abbreviazione di un elenco di alcuni nomi (che sono stringhe), scorrere su alcuni nomi e, per ciascun nome, determinare se è troppo lungo; in tal caso, restituisci true ; se nessuno è troppo lungo, restituisci false .

Contrastare il codice precedente con solo la denominazione dell'argomento strings e la variabile di ciclo string , specialmente in un metodo più complesso. Dovresti guardare da vicino per vedere la differenza, invece dell'uso è ovvio da un'occhiata al nome.

Trovare un buon naming è sempre un compromesso tra più fattori. Non sarai mai completamente soddisfatto.

Detto questo, anche se la tua lingua madre non è così, considera che l'inglese è la lingua i cui token di linguaggio di programmazione sono formati. L'uso della sintassi simile all'inglese rende la lettura del codice più "fluente" poiché non vi sono "regole di lettura interrotte" ogni volta che viene trovata una parola chiave.

In generale, considera cose come object.method(parameters) per abbinare uno schema come subject.verb(complements) .

Il punto chiave, se devi supportare la programmazione generica, è scegliere un insieme valido e coerente di "verbi" (specialmente quelli che devono essere usati in algoritmi generici).

A proposito dei nomi, le classi dovrebbero essere nominate per quello che sono are (in termini di concetto), mentre gli oggetti per quello che sono are for .

Detto questo, tra list.add(component) e component.add_to(list) preferisci il primo. In generale i verbi "transitivi attivi" rappresentano meglio le azioni rispetto alle loro controparti passive o riflessive. A meno che il design non ti limiti.

Non preoccuparti della lunghezza dei nomi dei metodi. Assicurati che i nomi dei metodi riflettano chiaramente ciò che stanno facendo. Questo è fondamentale per qualsiasi altra cosa. Se ritieni che il nome del metodo sia troppo lungo, usa un dizionario dei sinonimi per trovare una parola più breve che significa la stessa cosa. Ad esempio, usa Find invece di Retrieve .

Inoltre, ciò che è altrettanto importante sono i nomi che scegli per le tue classi. Questi forniscono un sacco di contesto quando si guardano i nomi dei metodi. Una firma del metodo in questo modo:

public User Find(int userId);

è più facile da capire di:

public Person Find(int personId);

perché il contesto ottenuto dal nome della classe User dice al programmatore che Find() è per individuare un tipo specifico di persona, l'utente del tuo sistema. La versione che utilizza la classe Person non offre alcun contesto sul motivo per cui dovresti persino utilizzare il metodo in primo luogo.

Guarda come gli altri sulla tua piattaforma lo fanno - alcuni dei giocatori più grandi potrebbero anche avere lo stile del codice e le linee guida per la denominazione.

Alcune piattaforme preferiscono i nomi brevi (ad esempio, nella API di Win32 C _tcsstr è la funzione per trovare una stringa all'interno di una stringa - non è ovvio?), altri vanno a favore della leggibilità a favore della brevità (in Apple Il framework Cocoa per Objective-C, il metodo per sostituire una sottostringa in una stringa con un'altra stringa e restituire il risultato come copia è chiamato stringByReplacingOccurrencesOfString: withString: ). Trovo che quest'ultimo sia molto più facile da capire e solo moderatamente più difficile da scrivere (specialmente con il completamento del codice).

Dato che leggi il codice più spesso di quanto lo scrivi (doppiamente vero per le librerie open source), e la lettura è più difficile della scrittura, ottimizzata per la lettura. Ottimizza per brevità solo l'ultima e prendi quanto più lontano possibile senza diluire la chiarezza.

1. Supponiamo che l'inglese, a meno che tutti gli sviluppatori che lavorano su questo codice parlino la stessa lingua non inglese.

2. Studia convenzioni e stili di denominazione comunemente accettati. Il tuo principio guida dovrebbe essere la chiarezza. Gli stili differiscono in base al linguaggio di programmazione.

3. Non c'è nulla che tu possa fare con la denominazione che renderà più facile comprendere le relazioni tra i vari oggetti nel tuo codice. Per questo, hai ancora bisogno di commenti e documentazione ben scritti.

1. Usa prefisso. Se un gruppo di metodi è usato per fare qualcosa di simile o può essere in qualche modo raggruppato, metti un prefisso comune prima dei loro nomi per mostrare ciò che questi metodi hanno in comune.
2. Non utilizzare l'abbreviazione non chiara se vuoi che gli altri capiscano immediatamente i nomi (importante nella denominazione dell'API)