Documento sugli standard

Question

Sto scrivendo un documento sugli standard di codifica per un team di circa 15 sviluppatori con un carico di progetto compreso tra 10 e 15 progetti all'anno.Tra le altre sezioni (che potrei postare qui non appena le avrò) sto scrivendo una sezione sulla formattazione del codice.Quindi, per cominciare, penso che sia saggio, per qualsiasi motivo, stabilire alcuni standard di base e coerenti per la formattazione/denominazione del codice.

Ho esaminato circa 10 progetti scritti negli ultimi 3 anni da questo team e, ovviamente, ho trovato una gamma piuttosto ampia di stili.Gli appaltatori entrano ed escono a volte, e talvolta addirittura raddoppiano le dimensioni della squadra.

Sto cercando alcuni suggerimenti per la formattazione del codice e gli standard di denominazione che hanno davvero dato i loro frutti...ma questo può anche essere davvero giustificato.Penso che la coerenza e i modelli condivisi contribuiscano notevolmente a rendere il codice più gestibile...ma ci sono altre cose che dovrei considerare nel definire tali standard?

• Come si allineano le parentesi?Segui le stesse linee guida per le parentesi quando hai a che fare con classi, metodi, prova blocchi catch, istruzioni switch, blocchi if else, ecc.

• Allinei i campi su una colonna?Annoti/prefissi le variabili private con un carattere di sottolineatura?Segui qualche convenzione di denominazione per facilitare la ricerca dei dettagli in un file?Come ordini i membri della tua classe?

Che dire dei suggerimenti per spazi dei nomi, pacchetti o standard di organizzazione/cartella del codice sorgente?Tendo a iniziare con qualcosa del tipo:

<com|org|...>.<company>.<app>.<layer>.<function>.ClassName

Sono curioso di vedere se ci sono altre pratiche più accettate di quelle a cui sono abituato, prima di avventurarmi a dettare questi standard.Anche i collegamenti agli standard già pubblicati online sarebbero fantastici, anche se ne ho già fatto un po'.

Answer 1

Per prima cosa trova un formattatore di codice automatizzato che funzioni con la tua lingua.Motivo:Qualunque cosa dica il documento, le persone inevitabilmente infrangeranno le regole.È molto più semplice eseguire il codice tramite un formattatore piuttosto che fare i pignoli in una revisione del codice.

Se stai utilizzando una lingua con uno standard esistente (ad es.Java, C#), è più semplice usarlo, o almeno iniziare con esso come prima bozza.Sun ha riflettuto molto sulle regole di formattazione;potresti anche approfittarne.

In ogni caso, ricorda che molte ricerche hanno dimostrato che variare cose come la posizione delle parentesi graffe e l'uso degli spazi bianchi non ha effetti misurabili sulla produttività, sulla comprensibilità o sulla prevalenza dei bug.Basta avere Qualunque la norma è la chiave.

Answer 2

Venendo dall'industria automobilistica, ecco alcuni standard di stile utilizzati per ragioni concrete:

Utilizza sempre le parentesi graffe nelle strutture di controllo e posizionale su righe separate.Ciò elimina i problemi con le persone che aggiungono codice e lo includono o non lo includono erroneamente all'interno di una struttura di controllo.

if(...)
{

}

Tutti gli interruttori/selezioni hanno un caso predefinito.Il caso predefinito registra un errore se non è un percorso valido.

Per lo stesso motivo di cui sopra, any if...elseif...le strutture di controllo DEVONO terminare con un else predefinito che registra anche un errore se non è un percorso valido.Una singola istruzione if non lo richiede.

Nel caso occasionale in cui un ciclo o una struttura di controllo è intenzionalmente vuota, viene sempre inserito un punto e virgola per indicare che ciò è intenzionale.

while(stillwaiting())
{
   ;
}

Gli standard di denominazione hanno stili molto diversi per typedef, costanti definite, variabili globali del modulo, ecc.I nomi delle variabili includono il tipo.Puoi guardare il nome e avere una buona idea di quale modulo si riferisce, del suo ambito e del tipo.Ciò semplifica il rilevamento degli errori relativi ai tipi, ecc.

Ce ne sono altri, ma questi sono la parte superiore della mia testa.

-Adamo

Answer 3

Asseconderò il suggerimento di Jason.

Ho appena completato un documento sugli standard per un team di 10-12 persone che lavora principalmente in Perl.Il documento dice di utilizzare "rientramento simile a perltidy per strutture di dati complesse". Abbiamo anche fornito a tutti le impostazioni di perltidy di esempio che avrebbero ripulito il loro codice per soddisfare questo standard.Era un linguaggio molto chiaro e molto standard del settore, quindi abbiamo avuto un ottimo consenso da parte del team.

Quando ho deciso di scrivere questo documento, ho chiesto in giro alcuni esempi di ottimo codice nel nostro repository e ho cercato un po' su Google per trovare altri documenti sugli standard che consentissero ad architetti più intelligenti di me di costruire un modello.È stato difficile essere concisi e pragmatici senza sconfinare nel territorio del micro-manager, ma ne è valsa davvero la pena;avendo Qualunque lo standard è davvero fondamentale.

Spero che funzioni!

Answer 4

Ovviamente varia a seconda delle lingue e delle tecnologie.Dall'aspetto del tuo spazio dei nomi di esempio indovinerò Java, nel qual caso http://java.sun.com/docs/codeconv/ è davvero un buon punto di partenza.Potresti anche voler guardare qualcosa come la struttura di directory standard di Maven che renderà tutti i tuoi progetti simili.