Come & # 8220; auto-documentare & # 8221; può essere il codice senza essere fastidioso? [chiuso]

Question

Non sono sicuro di quali siano le migliori pratiche qui, ma vedo spesso nomi di variabili abbreviati soprattutto quando l'ambito è piccolo. Quindi (per usare semplici esempi di Ruby) invece di def add_location (nome, coordinate) , vedo cose come def add_loc (nome, coord) & # 8212; e potrei vedere anche qualcosa come def add_loc (n, x, y) . Immagino che nomi più lunghi potrebbero stancare una persona quando sono abituati a vedere le abbreviazioni.

La verbosità aiuta la leggibilità o fa solo male agli occhi di tutti? & # 8212; Le persone preferiscono abbreviazioni e nomi abbreviati rispetto a nomi più lunghi?

Answer 1

Personalmente, preferirei molto vedere nomi più lunghi che in realtà significano qualcosa senza dover prima determinare il contesto. Naturalmente, le variabili che non danno un significato reale, come i contatori, utilizzo ancora piccoli nomi di variabili senza significato (come i o x ), ma altrimenti la verbosità è chiarezza il più delle volte. Ciò è particolarmente vero con le API pubbliche.

Questo può essere portato troppo lontano, tuttavia. Ho visto un po 'di codice VB in passato in quel modo ridicolo. Moderazione come tutto il resto!

Answer 2

In realtà utilizzo sempre nomi di variabili lunghe, dopo che tutti gli IDE e texteditor moderni hanno completato, quindi non c'è niente di sbagliato nell'usare index invece se i. L'unica eccezione che ho è quando ho a che fare con le coordinate b / c x e y hanno più senso lì.

Answer 3

Mai abbr.

Answer 4

A una variabile dovrebbe essere assegnato il nome più breve possibile che trasmetta adeguatamente il suo scopo.

L'eccessiva verbosità tende a nascondere la sintassi e la sintassi è importante.

In un intero programma (o applicazione / sistema) le variabili dovrebbero essere nominate con uno stile coerente e cose simili dovrebbero essere nominate in modo simile. Se esiste una convenzione all'interno della comunità linguistica, dovrebbe essere osservata (quindi non camelCaseRubyVariableNames) a meno che non ci siano ragioni convincenti per non farlo.

Le abbreviazioni, se utilizzate, devono essere applicate in modo coerente ovunque e, se specifiche del dominio, devono essere registrate da qualche parte. Se qualcuno passerà del tempo utile con il codice, imparerà presto.

Se hai bisogno di combinare fino a cinque o sei parole per nominare una variabile, suggerirei che potresti guardare un odore di codice e la routine che stai lavorando può trarre vantaggio da un po 'di lavoro.

Principalmente, tuttavia, se sei a conoscenza delle insidie ??e in realtà pensi a ciò che stai scrivendo, è probabile che il tuo codice sia ragionevole. Immagina di descrivere la funzione su cui stai lavorando a un nuovo collega: meno pensi di dover dire, migliore è probabilmente il codice.

Answer 5

Prova a leggere il tuo codice 1 anno dopo. Vedrai sia il valore dei nomi delle variabili auto-documentanti, sia il valore dei commenti del codice (e specialmente il valore del codice pulito)

Quando prendi qualcun altro codice sorgente e non lo capisci, è facile pensare " Beh, non è un buon programmatore come me " Ma quando ti rendi conto che il tuo codice è difficile da leggere, vai come: " che cosa stavo pensando? & Quot;

A lungo termine la verbosità aiuta la manutenibilità. Per uno script breve di una riga, puoi comunque utilizzare " setLocNm " anziché setLocationName "

Ogni pazzo può scrivere codice comprensibile a un computer. I bravi programmatori scrivono codice che gli umani possono capire. -Martin Fowler

Answer 6

Personalmente trovo che la verbosità sia una buona cosa, ma è anche facile essere troppo prolisso, il che è una cosa cattiva. C'è un equilibrio e anche le abbreviazioni possono entrare in tale equilibrio.

Queste sono le mie regole generali:

• Iteratori possono essere una lettera, ad es. i , j , k , ecc.
• Altre variabili di una sola parola come gli interruttori booleani, che cosa non hai mai abbreviato, cioè. installazione , fatto , ecc.
• Le variabili con più parole e i nomi delle funzioni sono candidati per l'abbreviazione, ma solo se iniziano a diventare ridicolmente lunghi (diciamo 20-25 + caratteri). L'abbreviazione intelligente è la chiave qui. function = > func ad esempio, ma mai fun , f o functi

Answer 7

Ho sfogliato le risposte, ma non vedo se è coperto quanto segue. Ecco qui ...

Sia che abbreviate o siate prolissi, assicuratevi di non aver usato più parole del necessario e che il significato sia dannatamente ovvio.

Ma anche dopo questo filtro se i tuoi identificatori sembrano dettagliati, hai un difetto nel tuo design.

def initialize_report_template()
end

avrebbe dovuto essere ...

class ReportTemplate
    def initialize()
    end
end

Answer 8

I nomi più lunghi sono molto meglio. Dici che vedi spesso nomi abbreviati in piccoli ambiti. Chi può dire che l'ambito rimarrà piccolo man mano che il software cresce?

Naturalmente, XCoordinateForCurrentLocationOfSelf è un nome ridicolo, quindi sii ragionevole. Soprattutto se stai entrando in un progetto su cui non hai mai lavorato prima, ringrazierai chiunque abbia usato la funzione descrittiva e i nomi delle variabili.

Answer 9

Penso che sia giusto abbreviare quando il nome danneggerebbe la leggibilità o sarebbe semplicemente ridondante.

Esempio 1: argomento di un metodo in cui il tipo trasmette già tutte le informazioni necessarie.

Esempio 2: una variabile che verrà utilizzata molto in modo ovvio

StringBuilder sb = ...
sb.append(...
sb.append(...
return sb.toString();

Esempio 3: abbreviazioni idiomatiche. i, j, k è già stato menzionato. & Quot; sb " sopra è uno nel nostro codice e ogni squadra ne ha probabilmente un altro paio.

Answer 10

Cerca di abbreviare e non di allungare, ma la comprensione del lettore dovrebbe superare pigrizia da digitare ogni volta.

Come altri hanno già detto, la lunghezza del nome della variabile non dovrebbe oscurare la logica o l'algoritmo. Ad esempio, in aritmetica, scriviamo

( 1 + 5 ) * 3 = 18

anziché

three multiplied by the sum of one and five equals eighteen

perché stiamo cercando di attirare l'attenzione su cose diverse dalla chiarezza degli elementi coinvolti nell'espressione.

Tendo a mantenere le variabili da una a tre parole, abbreviando solo quando supero i 24 caratteri circa. Meno frequentemente viene utilizzata una variabile, più è probabile che mi senta libero di prolungare il nome della variabile. Le variabili utilizzate più frequentemente le accorcerò.

Answer 11

Max Kanat-Alexander, il capo architetto di Bugzilla, dice questo sul suo blog:

  

Il codice stesso dovrebbe occupare spazio in proporzione al significato che ha.

     

Fondamentalmente, piccoli simboli che significano a   molto rende il codice difficile da leggere. Molto lungo   nomi che non significano molto anche fare   codice difficile da leggere. La quantità di   significato e lo spazio occupato dovrebbe   essere strettamente collegati tra loro.

http://www.codesimplicity.com/post/readability-and -naming-things /

È un post molto approfondito sulla denominazione delle cose. Invito tutti a leggerlo!

Answer 12

L'unica volta che accetto le abbreviazioni è per le variabili locali che rientrano nell'ambito solo per un breve periodo di tempo.

Significa che dovrebbero rientrare nell'ambito con un metodo o un costruttore molto leggibile.

Answer 13

Sono d'accordo con Kilhoffer; Preferisco vedere i nomi delle variabili descrittive in quasi tutti i contesti. Abbrevierò se i miei nomi di variabili sono più lunghi di circa 20 caratteri, di solito con parole nel nome della variabile (ad es. & Quot; SomeVeryLongVarValue ").

Certo, utilizzo anche la notazione ungherese ogni volta che posso, quindi potrei essere nell'altro campo estremo di cercare di rendere i nomi delle mie variabili eccessivamente descrittivi, a seconda della tua prospettiva.

Answer 14

Probabilmente sarò completamente fischiato ma volevo assicurarmi che questo punto di vista fosse ascoltato.

Mentre nomi di variabili più lunghi possono essere più descrittivi, possono iniziare a intaccare l'intento originale del programma. Ritengo che sugli elementi API sia importante avere nomi chiari e significativi nel contesto in cui verranno utilizzati.

All'interno di ogni funzione o metodo questa è spesso una storia diversa. Cerco di scrivere di meno e di mantenerlo molto conciso. Questo è noto come programmazione spartana al Mr. Atwood e questo nifty esempio. Sì, l'esempio è chiaramente truccato ma dimostra come avere un po 'meno cerimonia può effettivamente rendere più facile la lettura del programma.

Buona fortuna.

Answer 15

Durante la programmazione stai usando la sintassi in modo che gli umani possano leggerla, la lunghezza dei nomi delle variabili, i metodi, ecc ... sono davvero irrilevanti.

Più prolisso, meglio è di solito, con un buon ambiente di sviluppo dovresti comunque avere il completamento del codice, quindi puoi semplicemente premere " add_L " + TAB per terminare la chiamata del metodo.

Answer 16

Penso che il problema principale con le abbreviazioni sia che non tutte le persone abbreviano allo stesso modo , quindi quando lavori con molte persone può solo aumentare la probabilità di errore durante la codifica. Ad esempio se hai una costante che può essere chiamata SOMETHING_INTERFACE, forse alcuni sviluppatori potrebbero abbreviarla come SOMETHING_INTFACE, altri come SOMETHING_IFACE o SOMETHING_IF, SMTHING_IFACE ...

Con solo due parole puoi avere almeno una mezza dozzina di più o meno "logica" possibili abbreviazioni, quindi penso che sia meglio nella maggior parte dei casi scrivere senza abbreviazioni e con più motivi se si desidera avere un codice auto-documentato.

A volte nomi molto lunghi possono essere fastidiosi, ma possono anche essere abbreviati in ambiti molto locali usando variabili ausiliarie.

Answer 17

La maggior parte della gente vede la lettura, non ci vuole più leggere una parola e poi leggere una singola lettera. Quindi usa sempre nomi significativi. Devono essere descrizioni complete di 7 parole, no ma devono essere più lunghe da capire.

Potrei accettare add_loc (nome, coord), poiché sono abbastanza lunghi da poter dire cosa sono. In add_loc (n, x, y), obietterei a 'n' invece che a nome. Potrei vivere con X e Y poiché questi sono i nomi accettati delle coordinate.

Per qualcuno che non ha familiarità con i sistemi di coordinate ho potuto vedere dove add_location (nome, coordinate) sarebbe più significativo.

In caso di dubbi, utilizzare nomi più lunghi.

Answer 18

" Va bene capire i misteri dell'omicidio, ma non dovresti capire il codice. Dovresti essere in grado di leggerlo. & Quot; - Steve C. McConnell

Detto questo, se pensi che tu e nessun altro abbiate bisogno di nomi di variabili eccessivamente espliciti e così via, sentitevi liberi di accorciarli.

Answer 19

Suggerisco di adottare un approccio minimalista. Usa il meno possibile assicurandoti che il codice rimanga chiaro, conciso e puntuale.

Answer 20

Fuori dal campo di applicazione cose come costanti e globali dovrebbero avere nomi descrittivi lunghi. A volte un nome davvero lungo lo farà "odorare" quanto basta per segnalare la sua presenza come indesiderata. Questa è una buona cosa perché 1 - farà in modo che le persone lo evitino, 2 - aumenti la pressione per riformattare il codice per farlo sparire.