Creazione di un documento di standard di codifica

Quali sono gli aspetti chiave e i contenuti di un buon documento sugli standard di codifica?

1. Essere supportato da strumenti che consentono il controllo automatico del codice . Se so che non posso impegnarmi a controllare la versione di qualsiasi pezzo di codice che non corrisponde ad alcune regole, sarei incoraggiato a seguire tali regole nel mio codice. Se, d'altra parte, alcuni colleghi programmatori hanno scritto da qualche parte che devo seguire una regola, non me ne frega un cazzo di quelle regole.

2. Essere ben congegnato, invece di essere la tua opinione personale . Non si dice chiaramente: "d'ora in poi, non useremo più le regioni, perché non mi piacciono le regioni". Piuttosto, spiegheresti che le regioni incoraggiano la crescita del codice e non risolvono alcun problema grave .

   Il motivo è che nel primo caso il tuo collega risponderà: "bene, mi piacciono le regioni, quindi le userò ancora". Nel secondo caso, d'altra parte, costringerebbe le persone a non essere d'accordo con critiche costruttive, suggerimenti e argomentazioni, che alla fine ti faranno cambiare la tua opinione originale.

3. Essere ben documentato . La mancanza di documentazione crea confusione e spazio per l'interpretazione ; la confusione e la possibilità di interpretazioni portano a differenze di stile, vale a dire la cosa che gli standard vogliono sopprimere.

4. Essere diffuso, anche al di fuori della tua azienda . Uno "standard" utilizzato da venti programmatori è meno standard di uno standard noto a centinaia di migliaia di sviluppatori in tutto il mondo.

Dato che stai parlando di StyleCop, suppongo che l'applicazione sia scritta in uno dei linguaggi .NET Framework.

In tal caso, a meno che tu non abbia serie ragioni per fare diversamente, basta attenersi alle linee guida di Microsoft. Ci sono diversi vantaggi nel farlo piuttosto che creare i propri standard. Prendendo i quattro punti precedenti:

1. Non è necessario riscrivere le regole StyleCop in base ai propri standard. Non dico che sia difficile scrivere le tue regole, ma se puoi evitare di farlo, significa che hai più tempo a fare qualcosa di utile.

2. Le linee guida di Microsoft sono pensate molto bene. Ci sono possibilità che se non sei d'accordo con alcuni di loro, potrebbe essere perché non li capisci. Questo era esattamente il mio caso; quando ho iniziato lo sviluppo di C #, ho trovato alcune regole totalmente stupide. Ora sono completamente d'accordo con loro, perché finalmente ho capito perché sono stati scritti in questo modo.

3. Le linee guida di Microsoft sono ben documentate, quindi non devi scrivere la tua documentazione.

4. I nuovi sviluppatori che verranno assunti nella tua azienda in seguito potrebbero già avere familiarità con gli standard di codifica di Microsof. Ci sono alcune possibilità che nessuno avrà familiarità con il tuo stile di codifica interno.

La prima cosa importante da notare è che un documento standard di codifica non riguarda il bene e il male. Non si tratta di cose buone e cattive o quale metodo è migliore.

Lo scopo di un documento di standard di codifica è di assicurarsi che tutto il codice sia progettato, scritto e disposto allo stesso modo per rendere più facile per uno sviluppatore passare da un lavoro a un altro senza il necessario cambio di mentalità per leggere lo stile di qualcun altro .

Riguarda l'uniformità e nulla su "Giusto e sbagliato"

Con questo in mente alcune cose che dovresti chiarire in un documento di standard di codifica sono:

Convenzioni sui nomi

Come nominerete i vostri metodi, variabili, classi e interfacce? Quale notazione userete?

Anche qualcos'altro incluso nei nostri standard era uno standard separato per SQL, quindi avevamo nomi simili per tabelle, procedure, colonne, campi ID, trigger, ecc.

indentazione

Che cosa utilizzerai per l'indentazione? Una singola scheda? 3 spazi?

Layout

Le parentesi graffe verranno mantenute sulla stessa riga della linea del metodo di apertura? (generalmente java) o sulla riga successiva o su una linea a parte? (generalmente C #)

Gestione delle eccezioni / Registrazione

Quali sono i tuoi standard per la gestione delle eccezioni e amp; logging, è tutto fatto in casa o stai usando uno strumento di terze parti? Come dovrebbe essere usato?

Commentando

Abbiamo degli standard per dettare la correttezza grammaticale e che i commenti iniziano sulla linea prima o dopo, non sulla stessa riga, questo aumenta la leggibilità. I commenti devono essere rientrati alla stessa profondità del codice? Accetterete quei bordi di commento usati intorno a testi più grandi?

E i Metodi \\\ on per le descrizioni? Sono questi da usare? Quando?

esposizione

Tutti i tuoi metodi e campi dovrebbero implementare il livello di accesso più basso possibile?

Anche una cosa importante da notare. Un documento di buona qualità può aiutare a rivedere il codice, soddisfa questi standard minimi?

Ho appena graffiato la superficie di ciò che può entrare in uno di questi documenti, ma K.I.S.S.

Non renderlo lungo, noioso e impossibile da superare, o quegli standard non saranno seguiti, mantienili semplici.

Stavo passando attraverso questo processo più volte. E il metodo di maggior successo (anche se irregolare) è stato quello di prendere il documento "Coding Standards" dalla ben nota azienda e modificarlo in base alle proprie esigenze.

Ad esempio, ho appena trovato questo: link

Ad ogni modo, mantieni il tuo lanciafiamme a portata di mano.

Saluti,

Detesto la maggior parte dei documenti standard perché di solito cercano di ingannare le piccole cose e ignorano l'immagine più grande.

Ad esempio, quasi tutti diranno come nominare le variabili o posizionare le parentesi. Questo è puro stile e fa ben poco per aiutare un gruppo di codice devs correttamente. Ignorano cose come la struttura delle directory e il layout del codice. Ho visto documenti standard che ti dicevano esattamente quanti spazi mettere tra gli operatori e quante righe vuote mettere tra i metodi. Tutti questi di solito finiscono con un sacco di eccezioni alla regola che mostra solo quanto siano inutili, e poi sono così grandi che nessuno può seguirli, il che, di nuovo, rende ridicola il punto che stanno cercando di fare .

Ora per me, utilizzo molti diversi tipi di software da molte persone diverse e hanno tutti stili diversi. Mi sono semplicemente abituato a questo, non mi lamento che non c'è uno stile comune in tutti i gruppi di sviluppo. Finché il codice è uno stile comune in tutto il progetto, non mi interessa davvero quale sia lo stile. Quindi la mia prima regola per tutti i documenti standard è la seguente: Mantieni uno stile di codifica coerente all'interno del progetto . nessuno dovrebbe dare un fico dove sono le parentesi, a patto che siano tutte uguali. Prendi le guerre di religione e spingili:)

Il secondo è il layout del codice. Quando raccolgo un pezzo di codice, voglio vedere che è disposto su linee simili a quelle di altri lavori simili. Se ho un servizio web voglio che il nome del contratto wsdl sia chiaro, voglio che il nome dell'implementazione sia chiaro. Non voglio che qualcuno generi un layout nuovo e diverso per file e classi. Ciò significa che devo giocare "caccia il codice" che è una seccatura. Se sembra lo stesso dell'ultimo progetto su cui ho lavorato, posso immediatamente sapere dove trovare quello che sto cercando ed è probabilmente il più grande aiuto per lavorare con il codice di altre persone che conosco. Quindi, mantieni una struttura su come è strutturato il codice (ad es. Cartella di documentazione per documenti, interfacce per interfacce ecc. - qualunque cosa funzioni per te, ma atteniti ad essa).

Dovrebbero essere presenti anche artefatti del codice, quindi è necessario dire se la gestione degli errori prevista è costituita da eccezioni o codici di errore, ad es. Funzionalità di architettura del documento che è in uso . Dovrebbe anche indicare quale tipo di registrazione utilizzare e come presentare i registri / la gestione degli errori all'utente o qualsiasi altro sottosistema viene utilizzato per gestire il codice in natura. Ho lavorato in un posto dove ogni progetto ha fatto il logging in modo diverso - era patetico il modo in cui ogni rilascio di codice doveva avere un proprio, diverso, documento operativo che diceva ai ragazzi dell'opzione come dire se era andato storto. Il registro eventi, il file di registro (nel qual caso, dove), ecc. Sono tutti validi qui. Lo stesso vale per gli altri aspetti comuni del codice: come configurarlo (nessun punto utilizza un file .config per alcuni programmi o un DB personalizzato, o parametri della riga di comando, o registro per gli altri).

In breve, l'unica cosa che conta è Consistenza . E poiché enormi documenti standard sono troppo da leggere e memorizzare, preferisco semplicemente informare le persone di cose che non possono vedere (ad es. Standard architettonici come la registrazione) e dire loro di mantenere il codice che scrivono in modo coerente con ciò che è attualmente presente. E se non hai già il codice, allora non hai bisogno di un documento standard! (beh, non prima di aver scritto abbastanza per renderlo utile).

Quindi prendi da questo i punti principali: non provare a fare un documento legale , pensa a cose che non sono solo codifiche ma anche come funziona il codice e come il codice si adatta ad altre le aspettative della gente. Quindi fidati delle persone per fare un buon codice e vedrai che lo fanno. (e se non lo fanno puoi avere parole con loro, non c'è bisogno di deporla come legge).

No, è un totale spreco di tempo ed energia. StyleCop è eccezionale ed è stato creato negli anni da persone molto più esperte e più intelligenti di te o di chiunque altro nella tua squadra. Abbraccia e amalo! Ti guida continuamente, il che è migliore di qualsiasi documento in attesa di qualcuno che possa essere preso la briga di leggerlo.