Perché lo zio Bob suggerisce che gli standard di codifica non dovrebbero essere scritti se si può evitarlo?

Mentre stavo leggendo questa domanda , la risposta più votata citava lo zio Bob sugli standard di codifica , ma ero confuso da questo suggerimento:

3. Non scriverli se puoi evitarlo. Piuttosto, lascia che il codice sia il modo in cui vengono catturati gli standard.

Mi rimbalzò nel cervello, ma non riuscivo a trovare un posto dove restare. Se una nuova persona si unisce al team o cambia gli standard di codifica, non potrebbe esserci confusione di informazioni?

Perché non dovrei scrivere uno standard di codifica?

Ci sono alcuni motivi

1. Nessuno legge documentazione.
2. Nessuno segue la documentazione anche se la legge.
3. Nessuno aggiorna la documentazione anche se la legge e la segue.
4. Scrivere un elenco di pratiche è molto meno efficace della creazione di una cultura.

Gli standard di codifica non riguardano ciò che le persone dovrebbero fare, ma ciò che realmente fanno. Quando le persone si discostano dagli standard, questo dovrebbe essere raccolto e modificato attraverso un processo di revisione del codice e / o strumenti automatizzati.

Ricorda, il punto fondamentale degli standard di codifica è rendere le nostre vite più facili. Sono una scorciatoia per il nostro cervello in modo che possiamo filtrare le cose necessarie dalle cose importanti. È molto meglio creare una cultura di revisione per far valere questo piuttosto che formalizzarlo in un documento.

C'è un'altra interpretazione. Non credo sia lo zio Bob, ma vale la pena considerarlo.

Non acquisire standard di codifica in un documento. Catturalo nel codice, avendo un processo automatizzato che verifica il rispetto degli standard .

Non fare affidamento sulle persone che fanno riferimento a un documento, ma allo stesso tempo, non fare affidamento sulle persone che interpretano il codice già esistente e identificano ciò che è convenzionale e ciò che è coincidenza.

Incorporare qualcosa come Checkstyle nella build di commit. Questo può far rispettare le regole di base come la formattazione e gli standard di denominazione, e quindi piuttosto che spendere uno sforzo mentale nel considerare lo stile, che possono essere tutti scaricati in un processo stupido che almeno è garantito per essere accurato.

Se è importante, allora definisci rigorosamente ciò che vuoi e fallisci se è sbagliato.

Le persone trascurano il vero scopo di un documento sugli standard di codifica, che è quello di risolvere le controversie .

La maggior parte delle decisioni nello standard di codifica avrà solo un effetto molto minore sulla leggibilità e sulla produttività. Soprattutto se si adotta lo stile "normale" per il linguaggio e i progettisti del linguaggio stanno iniziando a rendersi conto che questo dovrebbe far parte delle specifiche (ad es. Go).

Perché sono così banali, gli argomenti possono essere davvero accesi e continuare all'infinito, danneggiando la produttività e la coesione del team. Oppure puoi oscurare la tua storia di cambiamento con una riformattazione infinita tra due o più stili preferiti di due persone.

Avere uno standard scritto pone fine all'argomento. I manager possono indicarlo e deviare l'insoddisfazione verso il documento. Puoi discutere con un pezzo di carta ma non ti ascolterà.

(Vedi anche The Tyranny of Structurelessness )

Perché i commenti sono bugie .

Lo standard di codifica è un grande commento su ciò che dovrebbe essere il codice. Il codice stesso è l'ultima fonte di verità. La verità in questo caso non è il comportamento del codice, è lo stile in cui è espressa. Se i tuoi standard non sono già riflessi nel tuo codice, hai molto lavoro da fare.

Lo zio Bob vede un commento come un fallimento personale del programmatore, perché dimostra che non è riuscito a esprimere lo scopo del frammento di codice con il linguaggio di programmazione stesso. Allo stesso modo, un documento standard non è in grado di esprimere uno stile coerente nella base di codice.

I nuovi programmatori dovrebbero passare il tempo a guardare il codice, non passare giorni a leggere un documento sugli standard multi-capitolo (ho dovuto farlo, sospiro).

Un documento sugli standard non è una cattiva idea, ma sono stato in negozi di programmazione in cui mantenere i documenti sugli standard era il lavoro a tempo pieno di qualcuno. Per favore, se devi conservare un documento standard, conservalo in una pagina. Ma se hai già il codice, nessuno dovrebbe essere in grado di mettere insieme lo stesso documento in meno di un giorno?

Avere standard di codice è importante. Avere un documento che detta ciò che sono non lo è.

Perché lo zio Bob suggerisce che gli standard di codifica non dovrebbero essere scritti se si può evitarlo?

Se stai chiedendo ragioni dietro la sua opinione, potresti avere una risposta solo se pubblicherà una risposta qui (la nostra opinione è solo irrilevante), tuttavia ...

Perché non dovrei scrivere uno standard di codifica?

Se stai chiedendo se ha ragione : lasciami essere l'unico impopolare (finora) a dire che non hai motivo di evitarlo.

SCRIVICI . Comunque proverò a spiegare i miei motivi ...

David ha suggerito in un commento che il punto principale della risposta di Stephen non è il motivo per cui non dovresti scrivere documenti ma in che forma sono. Se le linee guida sono formalizzate in strumenti (non semplicemente revisione del codice manuale), potrei essere d'accordo (quando la legge non richiede qualcos'altro). Si prega di notare che sfortunatamente gli strumenti non possono controllare tutto (la teoria del calcolo non è nostra amica) spesso perché sono limitati a una specifica unità di traduzione o pacchetto o qualunque sia la vostra lingua preferita che definisca un limite .

Tuttavia la formulazione di zio Bob non mi fa pensare che ne stia parlando.

Posso essere in disaccordo con un tale esperto senior? Lo faccio, per quasi tutti i punti citati (vedi anche la seconda parte di questa risposta per i dettagli). Proviamo a capire perché (supponendo che tu sappia già che le linee guida per la codifica non riguardano solo piccoli problemi di formattazione ).

• In alcune circostanze gli standard di codifica scritti sono richiesti dalla legge.
• Leggo la documentazione e sono sicuro di non essere solo. I membri del team possono cambiare nel tempo, le conoscenze non possono essere contenute in una base di codice di 5-10 anni o nelle menti dei membri del team. Le organizzazioni dovrebbero licenziare le persone che non seguono le linee guida interne.
• Gli standard di codifica, una volta che sono stati approvati , non cambieranno spesso e, se lo fanno, vuoi saperlo. Se gli standard sono cambiati, la documentazione (nel codice) non è aggiornata perché tutto il codice non segue il nuovo standard. La riformattazione / refactoring può essere lenta ma devi sempre seguire una guida autorevole da seguire.
• È meglio leggere un documento di 5 pagine piuttosto che ispezionare LOC 10 / 20K per estrapolare una regola (che potresti capire erroneamente, BTW), senza dubbio.
• È ironico che qualcuno che ha scritto molti libri sui principi di progettazione e lo stile di programmazione stia suggerendo che non dovresti scrivere le tue linee guida, non è meglio se ci scaricasse con alcuni esempi di codice? No, perché le linee guida scritte non solo ti dicono cosa fare ma anche altre due cose di cui manca il codice: cosa non fare e ragioni per farlo o no.

"Programmazione auto-organizzata gratuita" è un bene per un ragazzo ninja di 16 anni, ma le organizzazioni hanno altri requisiti :

• La qualità del codice deve essere garantita (e definita) a livello aziendale - non è qualcosa che può decidere un singolo team. Potrebbero anche non avere le competenze per decidere cosa c'è di meglio (quanti sviluppatori, ad esempio, hanno tutte le competenze necessarie per rivedere MISRA o anche semplicemente comprendere ogni regola?)
• I membri possono essere spostati in team diversi: se tutti seguono gli stessi standard di codifica, l'integrazione è semplice e meno soggetta a errori.
• Se un team si auto-organizza, gli standard si evolveranno nel tempo quando i membri del team cambiano - avrai quindi una base di codice enorme che non segue gli standard attualmente accettati .

Se stai pensando alle persone prima del processo, posso solo suggerire di leggere su TPS: gli esseri umani sono una parte centrale di Lean ma le procedure sono altamente formalizzate.

Naturalmente una piccola organizzazione con un solo team può lasciare che il team decida gli standard da adottare, ma deve essere scritto. Qui su Programmers.SE puoi leggere i post di Eric Lippert: suppongo che siamo tutti d'accordo che è uno sviluppatore esperto, quando ha lavorato per Microsoft ha dovuto aderire alle linee guida scritte (anche se alcune regole potrebbero essere errate , non applicabili o inutili a lui.) E Jon Skeet? Le linee guida di Google sono piuttosto rigide (e molte persone non sono d'accordo con loro) ma deve aderire a tali linee guida. È irrispettoso per loro? No, probabilmente hanno lavorato per definire e migliorare tali linee guida, una società non è composta da un membro (o una squadra) e ogni squadra non è un'isola .

Esempi

• Hai deciso di non utilizzare l'ereditarietà multipla e le classi nidificate in C ++ perché i membri effettivi del team non lo comprendono bene . Successivamente qualcuno che desidera utilizzare l'ereditarietà multipla deve esplorare l'intero 1M LOC per vedere se è mai stato utilizzato. È negativo perché se le decisioni di progettazione non sono documentate, è necessario studiare l'intera base di codice per capirle. E anche allora, se non è stato usato, è perché è contro lo standard di codifica, o è permesso, ma non c'erano situazioni precedenti in cui l'ereditarietà multipla era adatta?
• In C # c'erano metodi sovraccarichi per fornire parametri predefiniti perché la base di codice è stata avviata quando i parametri opzionali non erano disponibili in C #. Quindi hai cambiato e hai iniziato a usarli (refactoring del vecchio codice per usarli ogni volta che dovevi modificare tali funzioni). Anche più tardi hai deciso che i parametri opzionali sono sbagliati e inizi a evitare di usarli. Qual è la regola che ti dice il tuo codice? È un male perché lo standard si evolve ma la base di codice è più lenta da evolvere e se è la tua documentazione allora sei nei guai.
• Jon si è trasferito dalla squadra A alla squadra B. Jon deve imparare un nuovo standard; durante l'apprendimento probabilmente introdurrà bug più sottili (o, se fortunato, impiegherà molto tempo a capire il codice esistente e ad allungare la revisione del codice).
• Il team A passa a una base di codice precedentemente di proprietà del team B. Ha standard di codifica completamente diversi. Riscrivere? Adattare? Mescolare? Sono tutti ugualmente cattivi.

Zio Bob

Lasciateli evolvere durante le prime iterazioni.

È vero, fino a quando non si dispone di uno standard e l'organizzazione non ha assegnato il compito di crearne uno.

Lascia che siano specifici del team anziché specifici dell'azienda.

No, per tutte le ragioni spiegate sopra. Anche se pensi di formalizzare solo la formattazione del codice (la cosa meno utile che potresti voler formalizzare) ho ancora memoria di guerre infinite (e inutili) sulla formattazione. Non voglio viverli ancora e ancora, impostalo una volta per tutte.

Non scriverli se puoi evitarlo. Piuttosto, lascia che il codice sia il modo in cui vengono catturati gli standard.

No, per tutte le ragioni spiegate sopra (ovviamente a meno che non riformatterai tutto il codice in un colpo solo quando cambieranno le linee guida). Vuoi lasciare il tuo codice così com'è? Come si ispeziona la base di codice per comprendere le linee guida attuali ? Ricerca per età dei file e adattamento del tuo stile di codifica all'età dei file di origine?

Non legiferare sul buon design. (es. non dire alle persone di non usare goto)

È vero, le linee guida devono essere brevi o nessuno le leggerà. Non ripetere l'ovvio.

Assicurati che tutti sappiano che lo standard riguarda la comunicazione e nient'altro.

Non solo, un buon standard riguarda la qualità a meno che non si desideri avere uno standard solo per dettagli minori .

Dopo le prime iterazioni, riunisci la squadra per decidere.

Vedi il primo punto e non dimenticare che uno standard di codifica è di solito un processo che ha richiesto molti anni per essere sviluppato e perfezionato: poche iterazioni, forse con sviluppatori junior? Veramente? Vuoi fare affidamento sulla memoria di un membro senior (se presente)?

Tre note:

• A mio avviso gli svantaggi sono più gravi in ​​alcuni linguaggi rispetto ad altri, ad esempio in C ++ uno standard a livello aziendale è ancora più necessario che in Java.
• Questo ragionamento potrebbe non essere del tutto applicabile (e le ragioni di zio Bob potrebbero essere meno estreme ) se lavori in una società molto piccola in cui hai solo una piccola squadra.
• Sei assunto (come squadra) e lavorerai da solo con un nuovo progetto, poi lo dimenticherai e andrai avanti. In questo caso si potrebbe non si cura (ma il tuo datore di lavoro dovrebbe ...)

1. Per essere utile uno standard di codifica non deve parlare di questioni sostanziali; solo questioni di stile. Dovrebbe specificare solo quelle cose che sono arbitrarie e ambigue. ad es. posizionamento parentesi graffa, profondità di rientro, spazi vs schede, convenzioni di denominazione, ecc.
2. I problemi di stile sono locali, non globali. Ogni squadra dovrebbe adottare il proprio stile peculiare, adeguato al proprio compito e alla propria personalità. Ciò mantiene gli standard semplici e leggeri. Gli standard aziendali diventano sovraccarichi di tutte le possibili considerazioni, configurazioni ed eccezioni.
3. All'interno di un team, l'unico motivo per scrivere un documento di stile di codifica separato è se il codice prodotto dal team non soddisfa lo standard. Nel qual caso non hai standard. Per essere efficace, lo standard dovrebbe essere espresso dal codice stesso. E se è così, non è necessario un documento separato.
4. Nei sistemi legacy i team e gli stili cambiano nel tempo. Non c'è niente di sbagliato in questo. Il vecchio codice avrà uno stile più vecchio. Il codice più recente avrà uno stile più recente. Il team dovrebbe essere consapevole degli stili e della loro età. Ogni volta che viene scritto un nuovo codice, dovrebbe essere nel nuovo stile, indipendentemente da dove si trova il codice.

Perché non dovrei scrivere uno standard di codifica?

Ci sono molte ragioni per questo. Ecco alcune considerazioni:

1. Quanto tempo impiegano le persone a "apprendere" gli standard di codice solo per avere un sacco di tempo in tutto il team per rivedere, discutere, documentare, rivedere ... ecc. Gli standard di codice. È come discutere costantemente del tuo "Manuale per i dipendenti" - con che frequenza lo iscrive all'ordine del giorno di una riunione di gruppo ??

2. Quando un progetto viene rimborsato / accantonato / ecc. quindi le poche persone che rimangono di solito non possono continuare ad aderire (o forse non hanno nemmeno letto) gli standard. La prossima cosa che sai, tutto quello sforzo per "mantenere pulito il codice" è stato praticamente sprecato comunque.

3. Se il progetto si blocca o viene introdotto un nuovo lead, è molto probabile che la persona ignori totalmente le regole precedenti e voglia farlo in un modo nuovo. Ancora una volta, cosa è stato ottenuto codificando gli standard ??

Dovresti essere sicuro di leggere # 6:

Dopo le prime iterazioni, riunisci la squadra per decidere.

In altre parole, quando è il momento di avviare un progetto, segui il flusso per un po '. Quindi discuti le regole generali degli standard di codifica che il team attuale sta usando e sostanzialmente seguili. In questo modo, si massimizza lo sforzo per migliorare il prodotto minimizzando allo stesso tempo lo sforzo necessario per scrivere, rivedere e documentare lo "zucchero sintattico" che è stato impiegato per ottenere il codice eseguibile.

Pochissimi team traggono enormi vantaggi dagli standard di codifica. Di solito, la "leggibilità" è troppo vaga - e la maggior parte degli sviluppatori non beneficia molto delle regole esatte su spaziatura, nuove linee, ecc. Ma puoi evitare gli sviluppatori costantemente fastidiosi avendo almeno alcune regole.

Un'altra risposta che non credo sia stata dichiarata abbastanza chiaramente è che significa anche che le persone non seguono ciecamente le regole. Significa che le persone devono trovare giustificazioni effettive per le loro decisioni di progettazione e le convenzioni di codifica, piuttosto che dipendere dal fatto che è stato scritto per giustificarlo.

In primo luogo, per quanto ne so, lo zio Bob è una persona Java, questo è molto importante per capire cosa dice.

Quando lavoro in un team Java o C #, se il codice attuale è stato scritto da sviluppatori esperti, è facile per me imparare lo stile di programmazione e tenerlo aggiornato. Se non sono disposto a farlo, forse non ero la persona giusta per il lavoro ... Se non ci sono revisioni del codice o coppie di programmazione per venirmi a prendere quando non seguo lo stile, allora l'azienda ha un problema più grande rispetto al modo in cui nomina i campi membro!

Sia Java che C #, insieme alla maggior parte dei linguaggi moderni, sono stati definiti in modo che ci siano poche trappole "semplici" in cui cadere un programmatore.

Tuttavia, quando ho iniziato a programmare stavo usando C (e successivamente C ++). In C puoi scrivere codice come

if (a = 3);
{
   /* spend a long time debugging this */
}

Il compilatore non genererà un errore, ed è difficile da individuare quando si legge un sacco di codice. Tuttavia, se scrivi:

if (3 = a)
{
   /* looks odd, but makes sense */
}

Il compilatore dà un errore ed è facile cambiare il codice in 3 == a. Allo stesso modo, se lo standard di codifica non consente =di essere utilizzato in una ifcondizione o " ifistruzione vuota ", è possibile utilizzare un correttore di codice come parte del sistema di generazione per tenere traccia di questo errore.

Le mie opinioni sugli standard di codifica sono cambiate notevolmente quando mi sono allontanato da C / C ++: mi piacevano gli standard di codifica rigorosamente applicati e lunghi in molte pagine. Ora penso che devi solo elencare gli strumenti utilizzati e ottenere un accordo informale tra i membri del team originale su alcune convenzioni di denominazione. Non viviamo più in un mondo di team di oltre 30 sviluppatori che scrivono applicazioni in C / C ++ ...

C'è una ragione per cui non mi è mai piaciuto JScript e penso che TypeScript sia la cosa migliore da anni nello sviluppo web. Mi aspetto che gli sviluppatori dell'interfaccia utente Web abbiano ancora bisogno di standard di codifica a causa di difetti nella progettazione di HTML / CSS / JScript ecc.

Avere la fonte come standard di codifica autocompattante implica due cose.

1. Le persone devono consultare la base di codice ed esaminarla per diventare collaboratori competenti. Questo è incredibilmente importante. La lettura delle linee guida per la codifica è una perdita di tempo rispetto all'immersione nella base di codice.
2. Ammette che differenze minori non sono importanti. È importante concordare e comprendere i principi di base. Mantenere uno stile coerente non è perseguito come l'arte per l'arte. Non consente ai nitpicker non creativi di infastidire e distrarre altre persone. Si tratta di facilitare la comunicazione attraverso il codice in un team.

Un documento di standard di codice frequentemente aggiornato e ben scritto può essere molto utile, ma di solito non è così. Il documento sugli standard non riflette gli attuali standard di codifica utilizzati dall'azienda poiché è molto difficile creare un documento di standard buono e ancor più difficile mantenerlo aggiornato.

Invece di avere un documento sugli standard di codifica scadente e fuorviante, è meglio non averne nessuno e lasciare che il codice stesso rappresenti tali standard. In entrambi i casi, la parte più importante è applicare gli standard nel codice e ciò richiede molto più di un semplice documento. Motivazione, processi, corsi di formazione, strumenti, ecc. Sono molto più importanti.

Una cosa molto importante che non è stata dichiarata abbastanza chiaramente è che gli standard di codifica sono come il linguaggio: si evolvono. Uno standard di codifica scritto si oppone a questo, e se non lo fa è continuamente obsoleto e inutile.

Non avere uno standard di codifica inchiodato non è poi così male. Se esegui revisioni tra pari al momento del check-in, ogni volta che qualcosa che non è conforme allo standard di codifica entra nel repository, ciò significa che 2 persone ci hanno pensato * e hanno deciso che il vantaggio di questa variazione supera l'incoerenza con il resto del codice.

Non avere uno standard scritto rimuove anche la burocrazia che impedirebbe a un team di un'azienda di provare una nuova variante dello standard di codifica per un nuovo progetto, sia perché vogliono provare qualcosa, o forse perché uno standard diverso ha applicazioni pratiche su alcuni degli strumenti automatizzati che usano.

La redazione di uno standard ha la tendenza a rimuovere una maggiore flessibilità rispetto a quanto inizialmente previsto, pur occupando un bel po 'di tempo che potrebbe essere speso a fare altre cose. Non sto dicendo che non dovresti mai scrivere gli standard di codifica, gli standard scritti hanno certamente i loro vantaggi, specialmente se i team che lavorano in diverse località lavorano sulla stessa base di codice.

Fortemente correlato: evoluzione degli standard di codifica, come li gestisci?

* Se le persone non pensano durante la revisione tra pari del codice al momento del check-in, i tuoi problemi sono molto più grandi dei semplici standard di codifica.

Cambiarli diventa un grosso ostacolo e le persone aderiranno in modo sicuro alla lettera della legge anziché impegnare il cervello e fare la cosa giusta.

Verrà un giorno in cui parte dello standard non sarà utile e peggiorerà il codice. Alcune persone aderiranno allo standard, perché è scritto e sono al sicuro, e perché le regole sono lì per essere seguite. Le persone che vogliono scrivere un buon codice piuttosto che un codice conforme allo standard saranno frustrate e arrabbiate. Ci saranno argomenti e disaccordi, mentre se lo standard non fosse scritto, ci sarebbero esplorazione e discussione.

Penso che molti post qui stiano confondendo lo standard di codifica con la guida di stile .

Accertarsi che i moduli sviluppati da team diversi abbiano le stesse opzioni di compilatore e ABI è una cosa diversa da quanti spazi sono rientrati.

Cose come il modo corretto di strutturare i file #include e di non inquinare lo spazio dei nomi globale in un file di intestazione devono essere documentati in modo che possano essere usati come checklist durante la codifica iniziale e le revisioni del codice.

In particolare "non usare XXX perché causa problemi di compatibilità con YYY" non è qualcosa che vedresti nell'esempio nel seguire altri codici, poiché non è presente. Quindi, lascia che il codice sia il modo in cui vengono catturati gli standard potrebbe non essere chiaro o completamente mancante per alcuni tipi di standard, e quindi questo non può essere un piano universale.

Qualcosa di gravemente pervasivo e importante come non usare eccezioni o non usare newin alcuni sistemi embedded non può essere semplicemente lasciato alla conoscenza della cultura comune, poiché "l'informazione è (solo) culturale" contraddice i principi fondamentali degli standard di produzione come ISO-9000, che il lo sviluppatore di questi sistemi embedded sta utilizzando (ad es. per applicazioni automobilistiche). Queste cose importanti devono essere documentate, firmate e archiviate in modo formale.

Questo vale per la codifica , non per lo stile .

Gli inventori di C e C ++ mostrano, ad esempio, l'uso di nomi in minuscolo e non di CaMelCaSe. Quindi perché così tanti sviluppatori non seguono l'esempio implicito della fonte? Lo stile della biblioteca standard e i materiali didattici canonici non dovrebbero essere lo stile implacito da seguire?

Nel frattempo, le persone fanno seguire l'esempio delle intestazioni libreria standard per le cose che non dovrebbero essere copiati, come l'uso di __Uglynomi per i parametri macro e la comprendono file di pattern non ripetizione.

Quindi avere cose spesso non è visto come uno stile importante, o al contrario avere esempi potrebbe non essere chiaro su cosa non dovrebbe essere seguito nel codice del progetto. Entrambi sono controesempi alla tesi secondo cui lo "stile" (o convenzioni di codifica) è meglio lasciare implicito.