C'è una scusa per i nomi di variabili brevi?

Questo è diventato una grande frustrazione con la base di codice in cui sto attualmente lavorando; molti dei nostri nomi di variabili sono brevi e non descrittivi. Sono l'unico sviluppatore rimasto sul progetto e non c'è documentazione su ciò che la maggior parte di loro fa, quindi devo dedicare tempo extra a rintracciare ciò che rappresentano.

Ad esempio, stavo leggendo un codice che aggiorna la definizione di una superficie ottica. Le variabili impostate all'inizio erano le seguenti:

double dR, dCV, dK, dDin, dDout, dRin, dRout
dR = Convert.ToDouble(_tblAsphere.Rows[0].ItemArray.GetValue(1));
dCV = convert.ToDouble(_tblAsphere.Rows[1].ItemArray.GetValue(1));
... and so on

Forse sono solo io, ma essenzialmente non mi ha detto nulla di ciò che rappresentavano, il che ha reso difficile la comprensione del codice. Tutto quello che sapevo era che si trattava di una variabile analizzata su una riga specifica da una tabella specifica, da qualche parte. Dopo alcune ricerche, ho scoperto cosa significano:

dR = radius
dCV = curvature
dK = conic constant
dDin = inner aperture
dDout = outer aperture
dRin = inner radius
dRout = outer radius

Li ho rinominati essenzialmente in quello che ho lassù. Allunga alcune linee, ma penso che sia un giusto scambio. Questo tipo di schema di denominazione viene tuttavia utilizzato in gran parte del codice. Non sono sicuro che si tratti di un artefatto da parte degli sviluppatori che hanno imparato lavorando con sistemi più vecchi o se c'è un motivo più profondo dietro di esso. C'è una buona ragione per nominare le variabili in questo modo o sono giustificato aggiornandole a nomi più descrittivi quando li incontro?

Sembra che questi nomi di variabili si basino sulle abbreviazioni che ti aspetteresti di trovare in un libro di testo di fisica che risolve vari problemi di ottica. Questa è una delle situazioni in cui nomi di variabili brevi sono spesso preferibili a nomi di variabili più lunghi. Se hai fisici (o persone che sono abituate a elaborare le equazioni a mano) che sono abituati a usare abbreviazioni comuni come Rin, Rout, ecc., Il codice sarà molto più chiaro con quelle abbreviazioni di quanto non lo sarebbe con nomi di variabili più lunghi. Inoltre, rende molto più semplice confrontare le formule di documenti e libri di testo con il codice per assicurarsi che il codice stia effettivamente eseguendo correttamente i calcoli.

Chiunque abbia familiarità con l'ottica riconoscerà immediatamente qualcosa come Rin come raggio interno (in un documento di fisica, inverrebbe visualizzato come un indice), Rout come raggio esterno, ecc. Sebbene quasi sicuramente sarebbero in grado di tradurre mentalmente qualcosa come innerRadiusper la nomenclatura più familiare, farlo renderebbe il codice meno chiaro a quella persona. Sarebbe più difficile individuare casi in cui una formula familiare fosse stata codificata in modo errato e renderebbe più difficile la traduzione di equazioni in codice da e verso le equazioni che troverebbero in un documento o in un libro di testo.

Se sei l'unica persona che abbia mai visto questo codice, non dovrai mai tradurre tra il codice e un'equazione ottica standard, ed è improbabile che un fisico abbia mai bisogno di guardare il codice in futuro, forse lo fa ha senso rifattorizzare perché il vantaggio delle abbreviazioni non supera più il costo. Se questo fosse un nuovo sviluppo, tuttavia, avrebbe quasi certamente senso usare le stesse abbreviazioni nel codice che troveresti in letteratura.

Le variabili con tempi di vita brevi dovrebbero essere nominate a breve. Ad esempio, non scrivi for(int arrayCounter = 0; arrayCounter < 10; arrayCounter++) { .... Invece, usi for(int i ....

In generale, si potrebbe dire che più corto è il campo di applicazione variabile, più breve dovrebbe essere il nome. I contatori di loop sono spesso solo singole lettere, diciamo i, je k. Le variabili locali sono qualcosa come baseo frome to. Le variabili globali sono quindi un po 'più elaborate, ad esempio EntityTablePointer.

Forse una regola come questa non viene seguita con la base di codice con cui lavori. È una buona ragione per fare un po 'di refactoring!

Il problema con il codice non sono i nomi abbreviati, ma piuttosto la mancanza di un commento che spieghi le abbreviazioni o che indichi alcuni materiali utili sulle formule da cui derivano le variabili.

Il codice assume semplicemente la familiarità del dominio problematico.

Va bene, dal momento che è probabilmente richiesta la familiarità nel dominio del problema per comprendere e mantenere il codice, specialmente nel ruolo di qualcuno che lo "possiede", quindi ti conviene acquisire la familiarità piuttosto che aggirare i nomi allungati.

Ma sarebbe bello se il codice fornisse alcuni suggerimenti per fungere da trampolini. Anche un esperto di dominio potrebbe dimenticare che dKè una costante conica. Aggiungere un piccolo "cheat sheet" in un blocco di commenti non farebbe male.

Per alcune variabili che sono ben note nel dominio problematico - come nel caso che hai qui - i nomi delle variabili concise sono ragionevoli. Se sto lavorando a un gioco, voglio che le mie entità di gioco abbiano variabili di posizione xe y, non horizontalPositione verticalPosition. Allo stesso modo contatori di ciclo che non hanno alcuna semantica di là di indicizzazione, mi aspetto di vedere i, j, k.

Secondo "Clean Code":

I nomi delle variabili dovrebbero:

• Sii intenzionale a rivelare
• Evita la disinformazione
• Fai distinzioni significative
• Sii pronunciabile
• Sii ricercabile

Le eccezioni sono il proverbiale i,j,k,m,nusato per i loop.

La variabile di cui ti lamenti, giustamente, ti lamenti di non fare nulla di quanto sopra. Quei nomi sono cattivi nomi.

Inoltre, poiché ogni metodo deve essere breve , l'utilizzo dei prefissi per indicare l'ambito o il tipo non è più in uso.

Questi nomi sono migliori:

radius
curvature
conicConstant
innerAperture
outerAperture
innerRadius
outerRadius

Un commentatore afferma che questo sarebbe troppo complesso con nomi di variabili lunghe:

I nomi di variabili brevi non lo rendono nemmeno semplice:

fnZR = (r^2/fnR(1+Math.sqrt((1+k) * (r^2/R^2)))) + a[1]*r^2 + a[1]*r^4 + a[1]*r^6 ...;

La risposta è nomi lunghi e risultati intermedi fino a quando non ottieni questo alla fine:

thisNiceThing =  ( thisOKThing / thisGreatThing ) + thisAwsomeThing;

Esistono due buoni motivi per non rinominare le variabili nel codice legacy.

(1) a meno che non si stia utilizzando uno strumento di refactoring automatizzato, la possibilità di introdurre bug è elevata. Quindi, "se non è rotto, non aggiustarlo"

(2) farai il confronto tra le versioni attuali e le versioni precedenti, al fine di vedere cosa è cambiato, impossibile. Ciò renderà più difficile la futura manutenzione del codice.

C'è una buona ragione per nominare le variabili in questo modo o sono giustificato aggiornandole a nomi più descrittivi quando li incontro?

Il motivo per usare nomi più piccoli è se il programmatore originale li trova più facili da lavorare. Presumibilmente hanno il diritto di scoprire che è così e il diritto di non avere le stesse preferenze personali che hai. Personalmente, troverei ...

dDin better than dDinnerAperture
dDout better than dDouterAperture

... se li stessi usando in calcoli lunghi e complessi. Più piccola è l'espressione matematica, spesso è più facile vedere tutto in una volta. Anche se in tal caso, potrebbero essere migliori come dIn e dOut, quindi non c'era una D ripetitiva che potesse portare a un errore di battitura semplice.

D'altra parte, se trovi più difficile lavorare con te, poi buttati fuori e rinominalo nella loro forma più lunga. Soprattutto se sei responsabile di quel codice.

In generale, credo che la regola per questo, dovrebbe essere che puoi usare nomi di variabili estremamente brevi in ​​cui sai che le persone "esperte nell'arte" del tuo particolare codice capiranno immediatamente il riferimento di quel nome di variabile. (Hai sempre commenti ad eccezione di questo caso in ogni caso) e che l'uso localizzato delle variabili può essere facilmente individuato in base al contesto in cui vengono utilizzate.

Espandersi su questo, significa che non dovresti fare di tutto per offuscare i nomi delle tue variabili, ma puoi usare le abbreviazioni per i nomi delle tue variabili, dove sai che sono probabili solo le persone che capiscono il concetto alla base del tuo codice per leggerlo comunque.

Per usare un esempio del mondo reale, di recente, stavo creando una classe Javascript che avrebbe richiesto una latitudine e ti avrei detto la quantità di luce solare che ti aspetteresti in una determinata data.

Per creare questa lezione sulla Meridiana , ho fatto riferimento a forse mezza dozzina di risorse, l'Astronomia Almanacco e frammenti di altre lingue (PHP, Java, C ecc.).

In quasi tutti questi, hanno usato abbreviazioni identiche simili, che sulla sua faccia non significano nulla di assoluto.

K, T, EPS, deltaPsi, eot, LM,RA

Tuttavia, se hai conoscenza della fisica puoi capire cosa fossero. Non mi aspetto che nessun altro tocchi questo codice, quindi perché usare nomi variabili variabili?

julianTime, nutationOfEclipticalLongitudeExpressedInDegrees, equationOfTime, longitudeMean, rightAscension.

Inoltre, molte volte, quando i nomi delle variabili sono transitori, vale a dire, vengono utilizzati solo per allocare temporaneamente un valore, quindi spesso non ha senso utilizzare una versione dettagliata, specialmente quando il contesto della variabile spiega il suo scopo.

C'è assolutamente; spesso è sufficiente un breve nome di variabile.

Nel mio caso, sto effettuando la navigazione waypoint nella mia classe di robotica senior e programmiamo i nostri robot in KISS-C. Abbiamo bisogno di variabili per le coordinate correnti e di destinazione (x, y), distanze (x, y), intestazioni di corrente e di destinazione, nonché angoli di virata.

Soprattutto nel caso delle coordinate xey, un nome di variabile lungo è completamente inutile e nomi come xC (corrente x), yD (destinazione y) e pD (destinazione phi), sono sufficienti e sono i più facili da capire in questo caso.

Potresti sostenere che questi non sono "nomi di variabili descrittivi" come detterebbe il protocollo del programmatore, ma poiché i nomi si basano su un semplice codice (d = destinazione, c = corrente), un commento molto semplice all'inizio è tutta la descrizione richiedono.

C'è una buona ragione per nominare le variabili in questo modo o sono giustificato aggiornandole a nomi più descrittivi quando li incontro?

Di solito, algoritmi complessi sono implementati in matlab (o linguaggio simile). Quello che ho visto è che la gente ha appena assunto il nome della variabile. In questo modo, è semplice confrontare le implementazioni.

Tutte le altre risposte sono quasi corrette. Queste abbreviazioni si trovano in matematica e fisica, tranne che non iniziano con d(come nel tuo esempio). Le variabili che iniziano con d vengono generalmente denominate per rappresentare differenziazione .

Tutte le normali guide alla codifica dicono di non nominare le variabili con la prima lettera che rappresenta il tipo (come nel tuo caso), perché è così facile sfogliare il codice in tutti gli IDE moderni.

Posso pensare a una ragione per cui i nomi delle variabili siano ragionevolmente brevi.

I nomi brevi sono facili da leggere usando un intervallo di occhi più breve, quindi un breve intervallo di attenzione.

Ad esempio, una volta che mi sono abituato al fatto che svdb significa "salva nel database", la velocità di scansione del codice sorgente migliora poiché devo solo scansionare rapidamente 4 caratteri invece di leggere SaveToDatabase (14 caratteri, le cose peggiorano per nomi di operazioni più complessi). Dico "scansionare" non "leggere", perché ciò richiede gran parte dell'analisi del codice sorgente.

Quando si esegue la scansione di grandi quantità di codice sorgente, ciò può fornire buoni guadagni in termini di prestazioni.

Inoltre, aiuta il programmatore pigro a digitare questi nomi brevi durante la scrittura del codice.

Naturalmente, tutti questi "shorthands" dovrebbero essere elencati in una posizione standard nel codice sorgente.

Per inquadrare ciò che @zxcdw ha detto in un modo leggermente diverso ed elaborarlo in termini di approccio:

Le funzioni dovrebbero essere pure , brevi e un perfetto incapsulamento di alcune funzionalità: la logica della scatola nera , indipendentemente dal fatto che sia rimasta intatta per 40 anni, continuerà a fare il lavoro per cui è stata progettata, perché la sua interfaccia (dentro e fuori) è sano, anche se non sai nulla dei suoi interni.

Questo è il tipo di codice che vuoi scrivere: questo è il codice che dura ed è semplice da portare.

Se necessario, comporre le funzioni da altre chiamate di funzione (inline) , per mantenere il codice a grana fine.

Ora, con un nome di funzione adeguatamente descrittivo (dettagliato se necessario!), Minimizziamo ogni possibilità di interpretazione errata di quei nomi di variabili abbreviati, poiché l'ambito è così piccolo.

I nomi delle variabili dovrebbero essere il più descrittivi possibile per aiutare la leggibilità del programma. L'hai provato tu stesso: hai avuto molti problemi a identificare ciò che il programma ha fatto a causa della scarsa denominazione.

Non ci sono buoni motivi per non usare il nome descrittivo. Ti aiuterà e tutti gli altri che lavorano / lavoreranno al progetto. Bene, in realtà esiste un solo uso valido per i nomi brevi: contatori di loop.

Sicuramente questo è a cosa // commenti servono?

Se i compiti hanno commenti descrittivi, ottieni il meglio da entrambi i mondi: una descrizione della variabile e le eventuali equazioni sono facilmente confrontabili con la loro controparte del libro di testo.

Per le interfacce (ad es. Firme di metodi, firme di funzioni) tendo a risolverlo annotando le dichiarazioni dei parametri. Per C / C ++ questo decora il file .h e il codice dell'implementazione.

Faccio lo stesso per le dichiarazioni delle variabili in cui la conoscenza dell'uso della variabile non è ovvia nel contesto e nella denominazione. (Questo vale anche per le lingue che non hanno una digitazione forte.)

Ci sono molte cose che non vogliamo ostruire il nome della variabile. È l'angolo in radianti o gradi, esiste una certa tolleranza sulla precisione o sull'intervallo, ecc. Le informazioni possono fornire affermazioni preziose sulle caratteristiche che devono essere trattate correttamente.

Non sono religioso a riguardo. Sono semplicemente interessato alla chiarezza e ad assicurarmi che ora è quello che è la prossima volta che il mio io smemorato visita il codice. E chiunque mi guardi alle spalle ha ciò che deve sapere per vedere dove qualcosa è spento, ciò che è essenziale (l'ultimo critico per una corretta manutenzione).

Esiste una scusa per nomi di variabili eccessivamente brevi?

Primo: la denominazione di una variabile per l'energia e durante il calcolo di formule come E = MC2 NON è una denominazione eccessivamente breve. L'uso dei simboli come argomento per i nomi brevi non è valido

Questa domanda è stata piuttosto interessante per me, e posso solo pensare a una scusa e che è denaro.

Supponiamo ad esempio che stai collegando javascript a un client che sa che il file deve essere scaricato più volte al secondo. Sarebbe più economico e migliorerebbe l'esperienza degli utenti se il file (in numero di byte) fosse il più piccolo possibile.

(Solo per mantenere l'esempio "realistico", non ti è stato permesso di usare uno strumento di minificazione, perché? Problemi di sicurezza, nessuno strumento esterno ha permesso di toccare la base di codice.)

Noto che le altre risposte non menzionano l'uso della notazione ungherese. Questo è ortogonale al lungo dibattito, ma è rilevante per gli schemi di denominazione in generale.

double dR, dCV, dK, dDin, dDout, dRin, dRout

La "d" all'inizio di tutte queste variabili intende indicare che sono doppie; ma la lingua lo impone comunque. Nonostante la tresidezza di questi nomi, sono ridondanti fino al 50% !

Se utilizzeremo una convenzione di denominazione per ridurre gli errori, è molto meglio codificare le informazioni che non vengono controllate dalla lingua. Ad esempio, nessuna lingua si lamenterà dK + dRnel codice sopra, anche se non ha senso aggiungere un numero senza dimensioni a una lunghezza.

Un buon modo per prevenire tali errori è usare tipi più forti; tuttavia, se utilizzeremo i doppi, uno schema di denominazione più appropriato potrebbe essere:

// Dimensions:
// l  = length
// rl = reciprocal length
double lR, rlCV, K, lDin, lDout, lRin, lRout

La lingua ci consentirà comunque di scrivere K + lR, ma ora i nomi ci danno un suggerimento che ciò potrebbe non essere corretto.

Questa è la differenza tra sistemi ungheresi (generalmente non validi) e app ungheresi (possibilmente buoni)

http://en.wikipedia.org/wiki/Hungarian_notation

L' unico caso in cui nomi variabili variabili illegalmente accettabili sono accettabili nella moderna ingegneria del software è quando esistono in uno script e il throughput di quello script (su una rete in generale) è importante. Anche allora, mantieni lo script con nomi lunghi nel controllo del codice sorgente e minimizza lo script in produzione.