Cosa dovrebbe essere in uno standard di codifica? [chiuso]

Cosa dovrebbe esserci in un buono (leggi: utile) codice standard?

• Cose che il codice dovrebbe avere.
• Cose che il codice non dovrebbe avere.
• Lo standard di codifica dovrebbe includere definizioni di cose che il linguaggio, il compilatore o il formattatore di codice applicano?
• Che dire di metriche come complessità ciclomatica, linee per file, ecc.?

Un motivo per ogni esigenza. In questo modo, seguire lo standard non diventa una sorta di culto del carico e le persone sanno che è ok cambiare lo standard se il motivo non si applica più, o violare lo standard in casi specifici in cui il motivo chiaramente non si applica .

Tabs vs Spaces! Ottengo aggiornamenti pazzi quando uno dei miei colleghi impegna accidentalmente molte schede negli spazi che si spostano nel repository

Convenzioni di denominazione

EDIT: Con questo intendo le Linee guida per i nomi, non le Regole per i nomi.

Ad esempio, una linea guida sarebbe All boolean values should begin with Is/Can/Has/etc when possible. Una regola sarebbeAll boolean values must start with Is

Uno standard di codifica per un gruppo dovrebbe includere le opzioni del compilatore per avvisi ed errori che devono essere risolti.

I programmatori dovrebbero essere liberi di aumentare gli avvisi per il proprio codice, ma deve esserci una linea di base in modo che la lettura e l'utilizzo del codice di qualcun altro non ingombrino l'output che si ottiene dal compilatore.

Un simile standard dovrebbe anche riguardare il modo in cui i programmatori possono disabilitare tali avvisi caso per caso, nel caso in cui ci fosse un pezzo eccezionale di codice che altrimenti non sarebbe conforme.

Alcuni standard che mi piacciono (so che ce ne sono molti, ma quelli che preferisco):

• 80% di copertura dei test unitari
• Proprietà collettiva del codice (scrivere il codice che deve essere letto dai compagni di squadra, non dal compilatore)
• Scrivi commenti. Scrivi cosa vorresti dire a un nuovo arrivato.
• Mantienilo semplice

Gli standard di codifica aiutano un po 'quando scrivi il codice per la prima volta, aiutano molto quando tu o il tuo sostituto dovete aggiornare il codice 2 anni dopo.

Lo standard ideale porta al codice in cui è possibile passare a qualsiasi pagina arbitraria nel codice e comprendere esattamente cosa sta facendo al primo read-through, perché

• i nomi descrivono chiaramente quali dati vengono manipolati,
• le parentesi graffe rendono chiaro il flusso di controllo,
• i commenti spiegano qualsiasi algoritmo non ovvio, ecc.

D'altra parte, troppi standard arbitrari possono interrompere il flusso di scrittura del codice. Quindi credo che ogni elemento in una convenzione di codifica proposta debba essere valutato sulla base di questi 2 criteri:

• Questa regola aiuta a garantire che il codice sia corretto ?
• Questa regola aiuta a garantire che il codice sia Clear ?

Se nessuno dei due è vero, l'oggetto è solo arbitrario e probabilmente non necessario

Includerei le seguenti cose in uno standard che scrivo:

Per chiarezza:

• Organizzazione dei file: la specifica di un ordine fisso per gli elementi in un file consente al team di navigare facilmente negli altri file. Non dovresti cercare per trovare #define o definizioni di strutture.

• Convenzioni di denominazione: la denominazione coerente aiuta la leggibilità. Ma evita di specificare troppe regole, ciò danneggia la scrivibilità.

• Struttura del codice. Posizionamento di parentesi graffe, livelli di rientro, spazi vs tab, ecc. Sì, questa può essere una forte preferenza personale, ma l'obiettivo è un codice chiaro. Trova l'opzione migliore per la squadra e mantienila.

Per correttezza:

• Best practice specifiche per il tipo di problema: regole sull'allocazione della memoria, sulla concorrenza o sulla portabilità.

• "Costanti correzioni", uso corretto di statice volatile, ecc.

• Regole sulle macro del preprocessore e altre funzionalità della lingua facilmente abusate.

Idee ispiranti e pragmatiche che fanno pensare le persone, piuttosto che restrizioni negative che impediscono alle persone di pensare.

Altrimenti, ottieni scimmie in codice che hanno paura di inseguire le banane .

Cosa dovrebbe essere in uno standard di codifica? Più piccolo possibile. Meno piuttosto di più. E con giustificazione, per favore.

Non perché sono un programmatore di cowboy che non vuole alcun processo, ma perché ho visto specifiche di codifica pesanti senza alcuna logica dietro di esso (presumibilmente) "L'ho trovato su 'Net da qualche parte nel '95" che alla fine è diventato un incubo burocratico con cui lavorare.

Alcune persone sembrano onestamente credere che aumentando gli standard vedranno un corrispondente aumento della "qualità" del codice e forse con quella misura lo faranno. Nel frattempo ignoreranno l'architettura, le prestazioni, il buon senso e un sacco di altre cose che finiscono per essere più importanti del numero di righe in un file.

Una procedura per le revisioni del codice per applicare lo standard. Oh, e anche per trovare bug.

Qualche buon vecchio buon senso non andrebbe male; ci sono troppi documenti standard di codifica che lavorano su punti irrilevanti (elementi come il tipo di carattere e le dimensioni sono uno dei più estremi che abbia mai visto).

La cosa migliore da fare se fai parte di un gruppo di sviluppatori è parlare tra loro e guardare il tuo codice, formare un consenso su ciò che è accettabile e se devi annotare i punti principali come linee guida, ma tenerli come proprio quelle linee guida. Se non riesci a giustificare alcuna divergenza rispetto alle linee guida, dovresti davvero considerare il motivo per cui lo stai facendo.

Alla fine della giornata un codice chiaro e comprensibile è più importante di qualsiasi regola rigida sul layout o sulla tipografia.

Come altri hanno già detto, la copertura del test del codice è importante. Mi piace anche vedere:

• Struttura del progetto. I test fanno parte del codice o si trovano in una directory / progetto / pacchetto separata? Il codice dell'interfaccia utente vive con il back-end? In caso contrario, come viene suddiviso in compartimenti?

• Processo di sviluppo. Scrivi i test prima del codice? La correzione di build interrotte ha la priorità sullo sviluppo? Quando vengono eseguite le revisioni del codice e cosa dovrebbero riguardare?

• Gestione del codice sorgente. Cosa viene verificato quando? I documenti di progettazione e i piani di test sono controllati da revisioni? Quando ramifichi e quando tagghi? Mantenete build precedenti e, in caso affermativo, quante / per quanto tempo?

• Standard di distribuzione. Come viene confezionata una build? Cosa è necessario inserire nelle note di rilascio? Come vengono creati / controllati / eseguiti gli script di aggiornamento?

Dimentica tutte quelle stronzate sulle convenzioni di denominazione, la formattazione e quante righe possono essere in una funzione / metodo / modulo. Una regola: usa qualunque sia lo stile esistente in qualunque cosa tu stia modificando. Se non ti piace lo stile di qualcuno, selezionalo in una recensione di codice. L'unica eccezione potrebbe essere la cosa tabs-vs-space, se non altro perché molti editor / IDE convertiranno ciecamente l'uno nell'altro, e quindi finirai per distruggere la cronologia delle modifiche perché ogni riga è stata modificata.

Penso che in realtà ci siano due cose da affrontare, e in effetti le prenderei in considerazione separatamente perché non possono essere affrontate nello stesso modo, anche se le trovo entrambe importanti.

• L'aspetto tecnico: che mira ad evitare il codice rischioso o mal formato (anche se accettato dal compilatore / interprete)
• L'aspetto della presentazione: che si preoccupa di rendere chiaro il programma ai lettori

L'aspetto tecnico che mi qualifica di Coding Standard , così come Herb Sutter e Andrei Alexandrescu con i loro Standard di codifica C ++ . La presentazione mi qualifica di Coding Style , che include convenzione di denominazione, rientro, ecc ...

Standard di codifica

Poiché è puramente tecnico, uno standard di codifica può essere principalmente obiettivo. Pertanto ogni regola dovrebbe essere supportata da un motivo. Nel libro che ho indicato ogni articolo ha:

• Un titolo, semplice e preciso
• Un riassunto, che spiega il titolo
• Una discussione, che illustra il problema del fare diversamente e quindi afferma la logica
• opzionale Alcuni esempi, perché un buon esempio vale più di mille parole
• opzionale Un elenco di eccezioni per le quali non è possibile applicare questa regola, a volte con soluzioni alternative
• Un elenco di riferimenti (altri libri, siti Web) che hanno discusso di questo punto

La logica e le eccezioni sono molto importanti, in quanto riassumono il perché e il quando.

Il titolo deve essere abbastanza esplicito che durante le revisioni è sufficiente disporre di un elenco di titoli (cheat sheet) con cui lavorare. E ovviamente, raggruppa gli articoli per categoria per rendere più facile cercarne uno.

Sutter e Alexandrescu sono riusciti ad avere un elenco di solo un centinaio di voci, anche se C ++ è considerato peloso;)

Stile di codifica

Questa parte è generalmente meno obiettiva (e può essere decisamente soggettiva). L'intento qui è di garantire la coerenza, perché questo aiuta manutentori e nuovi arrivati.

Non vuoi entrare in una guerra santa su quale rientro o stile di parentesi è meglio qui, ci sono forum per questo: quindi in questa categoria fai le cose per consenso> voto di maggioranza> decisione arbitraria per leader.

Per un esempio di formattazione, vedere l'elenco delle opzioni di Stile artistico . Idealmente, le regole dovrebbero essere abbastanza chiare e complete da consentire a un programma di riscrivere il codice (anche se è improbabile che tu lo codifichi mai;))

Per la convenzione di denominazione, proverei a distinguere facilmente classe / tipi da variabili / attributi.

È anche in questa categoria che classifico le "misure" come:

• preferire metodi brevi o lunghi: di solito è difficile concordare quanto sia lungo
• preferisce il ritorno anticipato / continua / interrompi per ridurre il rientro

Varie?

E come ultima parola, c'è un elemento che raramente, se mai, viene discusso negli standard di codifica, forse perché è particolare per ogni applicazione: l'organizzazione del codice. Il problema architettonico è forse il problema più rilevante, rovina il progetto iniziale e ne rimarrai afflitto da anni. Dovresti forse aggiungere una sezione per la gestione dei file di base: intestazioni pubbliche / private, gestione delle dipendenze, separazione delle preoccupazioni, interfaccia con altri sistemi o librerie ...

Ma quelli non sono nulla se non sono effettivamente applicati e applicati .

Qualsiasi violazione dovrebbe essere sollevata durante le revisioni del codice e nessuna revisione del codice dovrebbe andare bene se una violazione è in sospeso:

• correggere il codice in modo che corrisponda alla regola
• correggi la regola in modo che il codice non risalti più

Ovviamente, cambiare una regola significa ottenere il "via libera" dai leader.

Mi piace il formato nelle Linee guida per la progettazione del framework che include una sezione generale e razionali per le linee guida. Il bit più utile sono i dettagli che iniziano con Do, Do Not, Avoid e Consider.

Ecco un esempio nella sezione Implementare i membri dell'interfaccia Esplicitamente ha i seguenti elementi (nota che ho lasciato cadere le motivazioni per il bene)

Evita di implementare esplicitamente i membri dell'interfaccia senza avere un valido motivo per farlo

Prendere in considerazione l' implementazione esplicita dei membri dell'interfaccia se si desidera che i membri vengano chiamati solo tramite l'interfaccia.

Non utilizzare membri espliciti come limite di sicurezza.

Non fornire un membro virtuale protetto che offre le stesse funzionalità come il> membro esplicitamente attuata se la funzionalità è destinata ad essere specializzati per classi derivate.

Questo crea un buon tono generale. Usando Evita e considera puoi consentire agli sviluppatori di usare il loro giudizio. Anche perché sono linee guida e non regole, è probabile che gli sviluppatori le trovino più appetibili e, a loro volta, abbiano maggiori probabilità di seguirle.

Nessuno sembra aver menzionato la sicurezza: in uno standard di codifica è necessario fare riferimento a requisiti di codice sicuri (ad es. L'uso di moduli di convalida dell'input, non consentite funzioni deboli note come strcpy, requisiti di gestione degli errori, ecc.)

Esempi. Esempi ben disposti, non banali, vicini al mondo reale che fanno uso di ogni regola. Commenti (non necessariamente parte del codice) quale parte dell'esempio segue quale regola.

Modelli. Non del tipo C ++, ma qualcosa da copiare e incollare e riempire con live. È molto più facile ottenere quel commento di 24 righe sulla caldaia quando hai un riferimento da cui copiare.

Caratteristica numero uno: un massimo assoluto di due pagine.

Questo è qualcosa che vuoi che ogni sviluppatore legga e ricordi. Non dovresti cercare nello standard ogni volta che devi scrivere una nuova funzione (o peggio una nuova riga). Quindi, mantienilo breve e mantieni solo le regole che forniscono davvero un valore maggiore al prodotto finale.

Gli standard di codifica sono in realtà diversi elementi:

Convenzioni di codifica

• queste cose non hanno bisogno di un motivo diverso dalla "coerenza della base di codice" per es. per usare '_' nelle variabili dei membri privati ​​o meno.
• potrebbero esserci diversi approcci corretti. Devo solo sceglierne uno per coerenza. per es. gestione degli errori mediante eccezioni o codici di errore.

Migliori pratiche

• questi articoli hanno sempre bisogno di una buona ragione con alcuni esempi chiari

per es. Non lasciare mai Catch vuoto dopo il tentativo

try { Foo(); } catch { //do nothing }

1) Se c'è un'eccezione generata da Foo () potrebbe causare altri problemi sulle funzioni che seguono, che presupponeva che foo avesse avuto successo.

2) Il gestore di errori globali non notifica l'eccezione al team di supporto quando si verifica su prod

• copre le pratiche di "codifica difensiva", come l'utilizzo degli Assert per testare i tuoi presupposti.

Ambiente di codifica

• strumenti che utilizza tutto il team. per es. VS 2010, Resharper, Forno, ecc.

Gli standard di codifica, se scritti su carta, sono molto efficaci. Mi piace come Go sta pubblicando il suo standard di codifica. Ha lo strumento gofmtper formattare il testo del programma in un formato. Qualsiasi dibattito sul formato di codifica risulterà quindi semplicemente come una patch per le fonti di gofmt.

Per quanto riguarda ciò che il formato dovrebbe avere,

• come nominare variabili, macro, costanti, valori letterali, funzioni, ecc
• come posizionare {,}, (,), [,] quando si tratta if, corpo della funzione, blocchi di istruzioni per altri scopi,
• quanto dovrebbero essere larghe le rientranze,
• quanti caratteri è consentita una riga di testo
• quanti livelli di rientri sono consentiti prima che il codice venga rifiutato / inviato per il refactoring
• quante righe di codice sono consentite per funzione prima di essere rispedite per il refactoring
• numero massimo di argomenti che una funzione può accettare prima di essere rispedita per il refactoring
• Alcune righe di commenti prima che una funzione inizi a spiegare brevemente cosa fa, se il corpo deve superare una pagina di codice sullo schermo; lasciando come l'oggetto viene raggiunto al codice nel corpo della funzione

Quando leggo il codice altrui (principalmente in linguaggio C), se i nomi di variabili / funzioni non sono intuitivi nel contesto del progetto o se supera i cinque livelli di rientro o le funzioni accettano più di sei o sette argomenti o una funzione viene eseguita per oltre due o tre pagine sullo schermo, diventa molto difficile leggere e comprendere il codice. Quando viene chiesto di eseguire lavori di miglioramento / manutenzione, aumenta solo la difficoltà. Mi fa venire voglia di gofmtscrivere un programma per ogni progetto (o persino lingua) e che ogni file di codice sorgente venga eseguito attraverso quel programma prima che venga inserito nel progetto.

Mi piace la Guida di stile JavaScript di Google .

È conciso nelle linee guida, ma contiene dettagli se ne hai bisogno.

Codice auto-documentante (commenti, nomi di variabili, nomi di funzioni, ecc.)