Creazione di un documento sugli standard di codifica

Lavoro in un'azienda di sistemi di controllo, dove il lavoro principale è SCADA e PLC , insieme ad altre cose sui sistemi di controllo.

Lo sviluppo del software non è realmente qualcosa che la società fa, a parte piccoli pezzi qua e là, fino a quando non è stata presa la decisione di creare un sistema interno di gestione e valutazione del progetto.

Questo progetto è stato accolto da persone che sono venute qui come software originariamente e siamo per lo più junior.

Il progetto è iniziato in piccolo, quindi abbiamo documentato solo cose come design, elementi del database ecc., Ma non abbiamo mai veramente concordato un formato / convenzioni di codifica.

Abbiamo iniziato a utilizzare StyleCop per assicurarci di avere un codice ben documentato, ma sento che abbiamo bisogno di un documento ufficiale per le convenzioni / pratiche di codifica in modo da poter continuare a un buon standard e se ci saranno altri importanti lavori di sviluppo in futuro, chiunque ci lavori ha una buona piastra di base.

Qui sta il problema, non ho idea di come redigere un documento per la codifica di convenzioni e standard, tutto ciò a cui riesco a pensare sono esempi di buone e cattive pratiche (ad esempio caso di cammello quando si nominano le variabili, evitando la notazione ungherese ecc.) Siamo tutti programmatori abbastanza competenti (apparentemente) ma non abbiamo una carta per questo tipo di cose.

Per chiarire la questione, la mia domanda è: quali sono gli aspetti chiave e i contenuti di un buon documento sugli standard di codifica?

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

1. Essere supportati da strumenti che consentono il controllo automatico del codice . Se so che non posso impegnarmi a controllare la versione di un pezzo di codice che non corrisponde ad alcune regole, sarei incoraggiato a seguire quelle regole nel mio codice. Se, d'altra parte, un altro programmatore ha scritto da qualche parte che devo seguire una regola, non me ne frega niente di quelle regole.

2. Essere ben ponderati, invece di essere la tua opinione personale . Non dite 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 .

   La ragione è che nel primo caso, il tuo collega avrebbe risposto: "beh, mi piacciono le regioni, quindi le userei comunque". Nel secondo caso, d'altra parte, costringerebbe le persone che non sono d'accordo a venire con critiche costruttive, suggerimenti e argomenti, alla fine facendoti 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 interpretazione portano alla differenza di stile, vale a dire la cosa che gli standard vogliono sopprimere.

4. Essere diffusi, anche al di fuori della tua azienda . Uno "standard" utilizzato da venti programmatori è meno standard di uno standard conosciuto da 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 seri motivi per fare diversamente, segui semplicemente le linee guida di Microsoft. Ci sono molti vantaggi nel farlo piuttosto che creare i tuoi standard. Prendendo i quattro punti precedenti:

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

2. Le linee guida di Microsoft sono molto ben pensate. Ci sono possibilità che se non sei d'accordo con alcuni di essi, 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é ho finalmente capito perché sono stati scritti in questo modo.

3. Le linee guida di Microsoft sono ben documentate, quindi non è necessario scrivere la propria documentazione.

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

La prima cosa importante da notare è che un documento sugli standard di codifica non riguarda il giusto e lo sbagliato. Non si tratta di buono e cattivo o quale metodo è migliore.

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

Si tratta di uniformità e niente di "giusto e sbagliato"

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

Convenzioni di denominazione

Come nominerai i tuoi metodi, variabili, classi e interfacce? Quale notazione userai?

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

dentellatura

Cosa userete per il rientro? Una singola scheda? 3 spazi?

disposizione

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

Gestione delle eccezioni / registrazione

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

Commentando

Abbiamo standard per dettare la correttezza grammaticale e che i commenti iniziano sulla riga prima o dopo, non sulla stessa riga, ciò aumenta la leggibilità. I commenti dovranno essere rientrati alla stessa profondità del codice? Accetterai quei bordi dei commenti usati attorno a testi più grandi?

Che ne dici di \\\ su Metodi per le descrizioni? Questi devono essere usati? 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 buone norme può fare molto per aiutare a revisionare il codice, soddisfa questi standard minimi?

Ho appena graffiato la superficie di ciò che può andare in uno di questi documenti, ma KISS

Non renderlo lungo, noioso e impossibile da raggiungere, o quegli standard non saranno rispettati, mantienilo semplice.

Stavo attraversando questo processo più volte. E l'approccio di maggior successo (anche se irregolare) è stato quello di prendere il documento "Coding Standards" da una società ben nota e modificarlo in base alle proprie esigenze.

Ad esempio, ho appena trovato questo: http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

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

Saluti,

Odio la maggior parte dei documenti standard poiché di solito cercano di sudare le piccole cose e ignorare il quadro generale.

Ad esempio, quasi tutti diranno come nominare le variabili o posizionare le parentesi. Questo è puro stile e fa ben poco per aiutare davvero 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 tra i metodi. Tutti questi di solito finiscono con una tonnellata di eccezioni alla regola che mostra solo quanto siano davvero inutili, e quindi sono così grandi che nessuno può seguirli, il che, ancora una volta, prende in giro il punto che stanno cercando di chiarire .

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

Il secondo è il layout del codice. Quando raccolgo un pezzo di codice, voglio vedere che è strutturato secondo 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 abbia un layout nuovo e diverso per file e classi. Ciò significa che devo giocare a "caccia al codice", il che è una seccatura. Se sembra lo stesso dell'ultimo progetto a 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 di come è strutturato il codice (ad es. Cartella Documentazione per documenti, interfacce per interfacce ecc. - qualunque cosa funzioni per te, ma atteniti ad esso).

Dovrebbero essere presenti anche artefatti di codice, quindi è necessario dire se la gestione degli errori prevista sono eccezioni o codici di errore, ad es. documentare la funzionalità architettonica in uso . Dovrebbe inoltre indicare quale tipo di registrazione utilizzare e come presentare i registri / la gestione degli errori all'utente o qualunque sottosistema venga utilizzato per gestire il codice in natura. Ho lavorato in un luogo in cui ogni progetto registrava diversamente: era patetico il modo in cui ogni versione del codice doveva avere un proprio documento operativo diverso che dicesse agli operatori come dire se era andato storto. Il registro eventi, il file registro (nel qual caso dove), ecc. Sono tutti validi qui. Lo stesso vale per altri aspetti comuni al codice: come configurarlo (nessun punto usando un file .config per alcuni programmi, o un DB personalizzato, o parametri della riga di comando o registro per altri).

In breve, l'unica cosa che conta è la coerenza . E poiché i grandi documenti sugli standard sono troppo da leggere e memorizzare, preferisco semplicemente informare le persone sulle cose che non riescono a vedere (ad esempio standard architetturali come la registrazione) e dire loro di mantenere il codice che scrivono coerente con ciò che è attualmente lì. E se non hai già il codice, non hai bisogno di un documento standard! (beh, non fino a quando non avrai scritto abbastanza per renderlo utile).

Quindi prendi da ciò i punti principali: non provare a creare un documento legale , pensa a cose che non sono solo codifica ma anche come funziona il codice e come il codice si adatta alle aspettative degli altri. 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 metterlo come la legge).

No, è una totale perdita di tempo ed energia. StyleCop è eccezionale ed è stato fondato nel corso degli anni da persone molto più esperte e molto più intelligenti di te o di chiunque nella tua squadra. Abbraccia e amalo! Ti guida continuamente, il che è meglio di qualsiasi documento in attesa di qualcuno che può essere disturbato a leggerlo.