Linee guida concise e significative per la denominazione dei metodi


25

Di recente ho iniziato a rilasciare un progetto open source, mentre ero l'unico utente della libreria non mi importava dei nomi, ma so che voglio assegnare nomi intelligenti a ciascun metodo per renderlo più facile da imparare, ma ho anche bisogno di usare nomi concisi, quindi sono anche facili da scrivere.

Stavo pensando ad alcune linee guida sulla denominazione, sono a conoscenza di molte linee guida che si occupano solo di lettere o semplici appunti. Qui, sto cercando le linee guida per una denominazione significativa ma concisa.

Ad esempio, questo potrebbe far parte delle linee guida che sto seguendo:

  • Usa Aggiungi quando un oggetto esistente verrà aggiunto a una destinazione, Usa Crea quando un nuovo oggetto viene creato e aggiunto a una destinazione.
  • Usa Rimuovi quando un oggetto esistente verrà rimosso da una destinazione, Usa Elimina quando un oggetto verrà rimosso in modo permanente.
  • Associare i metodi AddXXX a RemoveXXX e Associare i metodi CreateXXX ai metodi DeleteXXX, ma non mescolarli.

Come mostrano gli esempi precedenti, vorrei trovare del materiale online che mi aiuti con metodi di denominazione e altri articoli conformi alla grammatica inglese e ai significati delle parole.

La guida sopra può essere intuitiva per i madrelingua inglesi, ma per me che l'inglese è la mia seconda lingua, ho bisogno di sentir parlare di cose come questa.


Benvenuti nel sito! Questa domanda correlata può essere utile: programmers.stackexchange.com/questions/14169/…
Adam Lear

1
Penso che la parte concisa sia più importante della parte significativa, poiché il tuo schema è già significativo. Se hai intenzione di fare il possibile, fallo per coerenza.
yannis,

7
Descrittivo è più importante che conciso. La maggior parte dell'IDE offre il completamento, quindi la lunghezza non dovrebbe essere un ostacolo e i nomi descrittivi sono più facili da capire e ricordare.
Caleb,

@AnnaLear Sto chiedendo qualcosa di diverso, la mia domanda è collegata a cose come la terminologia suggerita per la denominazione o le note grammaticali che possono aiutare gli altri a comprendere meglio lo scopo del metodo.
000,

3
La lettura è più importante che concisa. Tutti gli IDE moderni dispongono di funzionalità di completamento del codice, quindi rendere più semplice scoprire cosa fa un metodo è più prezioso che semplificare la digitazione.

Risposte:


34

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

Quando chiamo qualcosa, ecco la mia serie di priorità:

  • Segui i modi di dire della mia lingua. A Ruby piacciono i caratteri di sottolineatura. A Javascript piace la custodia per 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 perdere i dettagli dell'implementazione. Dire, prefisso una variabile con un tipo.
  • Non utilizza più caratteri del necessario senza infrangere le linee guida precedenti.

Ovviamente questo è un approccio piuttosto semplicistico. La denominazione è sfumata.

Per ulteriori ricerche, consiglierei di leggere The Art of Readable Code , in quanto fornisce alcuni consigli eccellenti e concisi sulla denominazione del metodo. Per ulteriori ricerche non posso consigliare vivamente il codice pulito di Bob Martin


2
+1 per una buona risposta e raccomandare Clean Code. Consiglio vivamente anche questo libro. Un'altra cosa che aggiungerei, e questo è tratto dal libro di Martin: "Voglio che anche il codice sia facile da scrivere" ha una priorità molto più bassa rispetto alla capacità di leggere il codice. Ovviamente, esiste un nome troppo lungo, ma mi affiderei sempre a nomi lunghi più leggibili, rispetto a quelli facili da scrivere. Inoltre, la maggior parte degli IDE moderni si completano automaticamente.
DXM,

3
Un'altra idea importante dal libro di Robert Martin: Per i metodi: nome breve con ambito lungo, nome lungo con ambito corto. Per le variabili il nome inverso - short short scope, long scope long name.
Patkos Csaba,

"Clean Code" è stato il più grande libro che mi ha aiutato a capire l'impatto della leggibilità del codice e ha elencato le migliori pratiche che seguo regolarmente
Paul

Una domanda, che rivela l'intento nel nome del metodo, non influisce sulla riusabilità del metodo? post_twitter_status lo rende troppo specifico.
EresDev

Sì e no. Quel particolare metodo potrebbe essere meno riutilizzabile, ma puoi sempre estrarre un metodo con il comportamento principale, spostarlo in una classe più generica e lasciare il vecchio metodo come "cucitura". In questo modo, se è necessario evitare la duplicazione, è possibile senza cambiare l'interfaccia.
Zee

7

La tentazione di codificare uno stile o una convenzione per la denominazione può in alcuni casi portare ad abitudini che sono considerate cattive pratiche al giorno d'oggi, come ad esempio l'uso della notazione ungherese. La semplice risposta è dimenticare la convenzione di denominazione e lo stile come se fosse una cosa separata da determinare separatamente, e invece concentrarsi sulla denominazione di tutto nel sistema in base a ciò che effettivamente rappresenta. I nomi dei metodi tenderanno naturalmente ad essere concisi se si limita la funzionalità di ciascun metodo in modo che faccia solo una cosa teoricamente e se il nome del metodo in realtà descrive l'unica cosa che il metodo dovrebbe fare.

Variabili, campi, nomi di classi e file sono qualcos'altro. Suggerirei che se i nomi delle variabili stanno diventando troppo lunghi, allora stai provando a 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 un più astratto maniera.

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


6

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

  • Cosa fa la classe / metodo / variabile, ovvero qual è il suo scopo più ampio e a cosa serve?
  • Che cosa deve sapere in particolare riguardo al suo scopo, cioè qual è la parte essenziale che il nome deve avere in esso?

La maggior parte degli sviluppatori concorderebbe sul fatto che la leggibilità è sempre di fondamentale importanza quando si tratta di nominare. Non scrivere semplicemente codice in modo da sapere cosa intendi mentre lo scrivi, scrivilo in modo che qualcuno che guardi il codice per la prima volta ad un certo punto in futuro sappia cosa intendi senza dover pensare troppo. Scriverai il codice una sola volta, ma nel corso della sua vita dovrà probabilmente essere modificato più volte e letto anche più volte.

Il codice dovrebbe essere auto-documentato, cioè la tua denominazione dovrebbe rendere ovvio cosa fa qualcosa. Se hai bisogno di spiegare cosa fa una riga di codice in un commento, e rinominare le cose non la migliora abbastanza, dovresti seriamente considerare di rifattorizzare quella linea in un nuovo metodo con un nome adeguatamente descrittivo, in modo che leggendo il metodo originale, il la nuova chiamata del metodo descrive cosa sta succedendo. Non aver paura di avere nomi lunghi; ovviamente non dovresti scrivere romanzi in nomi di classe / metodo / variabile, ma preferirei che un nome fosse troppo lungo e descrittivo piuttosto che troppo breve e ho bisogno di capire cosa fa guardando sotto il cofano. Tranne alcune ovvie eccezioni come le coordinate x / y e gli acronimi comunemente usati, evita nomi e abbreviazioni a carattere singolo. Chiamare qualcosa "bkBtn" invece di "backButton"

Per quanto la tua lingua lo permetta, fai leggere il tuo codice come una frase inglese. Gli oggetti usano nomi, i metodi usano i verbi. I metodi booleani in genere iniziano con "is", ma ci sono molte altre opzioni che trasmettono il significato ancora meglio, a seconda del caso d'uso, come "can", "should" o "does". Ovviamente, non tutte le lingue possono essere buone come Smalltalk in questo, ma alcuni simboli sono generalmente considerati parti della frase. Due convenzioni di Smalltalk che personalmente mi piace prendere il più possibile in altre lingue sono il prefisso del nome dei parametri del ciclo con "ciascuno" e il prefisso dei parametri del metodo con l'articolo "a" (o "un", o "alcuni" per le raccolte) . Questo potrebbe non essere uno standard comune in Java e chiunque può ignorare questo bit, ma trovo che questo migliora 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 da persone con un po 'di conoscenza di Java come qualcosa del genere:

Per determinare se è necessario abbreviare un elenco di alcuni nomi (che sono stringhe), scorrere su alcuni nomi e, per ciascun nome, determinare se è troppo lungo; in tal caso, tornare true; se nessuno è troppo lungo, ritorna false.

Contrasta il codice sopra con la semplice denominazione dell'argomento stringse della variabile loop string, specialmente in un metodo più complesso. Dovresti guardare da vicino per vedere la differenza invece che l'uso sia evidente da uno sguardo al nome.


3

Trovare una buona denominazione è sempre un compromesso tra più fattori. Non sarai mai pienamente soddisfatto.

Detto questo, anche se la tua lingua madre non è quella, considera che l'inglese è la lingua i cui token dei linguaggi di programmazione sono formati. L'uso della sintassi inglese rende la lettura del codice più "fluente" poiché non ci sono "regole di lettura infrante" ogni volta che viene trovata una parola chiave.

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

Il punto chiave, se devi supportare la programmazione generica, è scegliere una buona e coerente serie di "verbi" (specialmente quelli che devono essere usati negli algoritmi generici).

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

Detto questo, tra list.add(component)e component.add_to(list)preferisco il primo. In generale i verbi "attivi transitivi" rappresentano meglio le azioni rispetto alle loro controparti passive o riflessive. A meno che non vi siano vincoli di progettazione.


2

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 significhi la stessa cosa. Ad esempio, utilizzare Findinvece di Retrieve.

Inoltre, ciò che è altrettanto importante sono i nomi che scegli per le tue lezioni. Questi forniscono un sacco di contesto quando si osservano 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 Userindica al programmatore che Find()è per individuare un tipo specifico di persona, l'utente del sistema. La versione che utilizza la Personclasse non fornisce alcun contesto sul motivo per cui dovresti persino utilizzare il metodo in primo luogo.


1

Guarda come lo fanno gli altri sulla tua piattaforma: alcuni dei giocatori più grandi potrebbero persino avere uno stile di codice e linee guida per la denominazione.

Alcune piattaforme preferiscono nomi brevi (ad esempio, nell'API C Win32 _tcsstrè la funzione per trovare una stringa all'interno di una stringa - non è ovvio?), Altri cercano leggibilità a favore della brevità (nel framework Cocoa di Apple per Objective-C , il metodo per sostituire una sottostringa in una stringa con un'altra stringa e restituire il risultato come viene chiamata una copia 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 tu lo scriva (doppiamente vero per le librerie open source) e la lettura è più difficile della scrittura, ottimizza per la lettura. Ottimizza per brevità solo per ultimo e togli solo il più possibile senza diluire la chiarezza.


1
  1. Supponi l'inglese, a meno che ogni sviluppatore che non lavori su questo codice parlerà 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'è niente che tu possa fare con la denominazione che faciliterà la comprensione delle relazioni tra i vari oggetti nel tuo codice. Per questo, hai ancora bisogno di commenti e documentazione ben scritti.


Anche se ogni sviluppatore che lavora sul codice parlerà non inglese, continuerà a usare l'inglese ...!
Mvision,

0
  1. Usa prefisso Se un gruppo di metodi viene utilizzato per fare qualcosa di simile o può essere in qualche modo raggruppato insieme, metti un prefisso comune prima dei loro nomi per mostrare ciò che questi metodi hanno in comune.
  2. Non usare abbreviazioni poco chiare se desideri che gli altri capiscano immediatamente i nomi (importante nella denominazione delle API)
Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.