Documentazione e applicazione degli standard di programmazione e linee guida per la libreria condivisa

4

Io e un altro sviluppatore con il vantaggio del nostro direttore IT abbiamo avviato una libreria per scopi generici in .NET con l'intenzione che fornirà molte classi di utilizzo comune che utilizziamo nel nostro sviluppo quotidiano.

Durante le discussioni e la progettazione della biblioteca abbiamo messo a punto una serie di standard che vogliamo che la libreria segua per assicurarne il mantenimento e l'espansione in modo coerente.

Qual è il modo migliore per garantire che queste decisioni prese per la biblioteca portino feed agli altri sviluppatori che potrebbero utilizzare e aggiungere a questa libreria in futuro. Una delle nostre decisioni era garantire che esaminassimo tutti i codici archiviati, quindi prevediamo inizialmente alcune differenze negli stili di codifica degli individui che non rientrano negli standard del progetto.

Alcune idee che ho avuto sono state:

  1. Aggiungi un file Read-me.txt al progetto che delinea le linee guida e gli standard
  2. Invia un'email a tutti i membri del team per informarli sul progetto ecc.
  3. Chiama una riunione del team per seguire questo nuovo progetto e le nostre aspettative e standard che intendevamo seguire
  4. Prova e applica gli standard tramite Visual Studio (non sono sicuro se ciò sarebbe possibile o come solo un'idea)

Al momento non ci sono standard generali di programmazione aziendale, quindi questo sarebbe il primo vero motivo per cui stiamo creando uno standard a cui i diversi team di progetto dovrebbero attenersi.

    
posta dreza 14.02.2012 - 21:19
fonte

3 risposte

4

Utilizza FxCop e StyleCop per analizzare e applicare regole che descrivono lo standard di codifica previsto per la tua libreria. Potresti anche scrivere un documento che spiega il tuo standard di codifica, ma usare l'analisi del codice è il modo migliore per applicarle concretamente.

Modifica

Vedi questa domanda per ulteriori informazioni sull'analisi del codice disponibile in alcune versioni di Visual Studio.

    
risposta data 14.02.2012 - 21:29
fonte
8

Generalmente è meglio applicare gli standard usando strumenti come analizzatore statico FXCop / Visual Studio e StyleCop .

StyleCop is an open source static code analysis tool from Microsoft that checks C# code for conformance to StyleCop's recommended coding styles and a subset of Microsoft's .NET Framework Design Guidelines. StyleCop analyzes the source code, allowing it to enforce a different set of rules from FxCop (which, instead of source code, checks .NET managed code assemblies). The rules are classified into the following categories:

  • Documentation
  • Layout
  • Maintainability
  • Naming
  • Ordering
  • Readability
  • Spacing

StyleCop includes both GUI and command line versions of the tool. It is possible to create new rules to be used.

StyleCop was re-released as an open source project in April 2010...

    
risposta data 14.02.2012 - 21:27
fonte
5

Lo stile interno del codice è una cosa secondaria IMHO - è molto più importante disporre di un insieme coerente di documentazione che insegna all'utente della libreria cosa è disponibile e come usarlo.

Da quello che devi iniziare, come intendi per andare avanti, scrivi questa documentazione con il formato e la profondità corretti, quindi aspettati che tutti i contributi forniscano un livello simile di documentazione. È difficile da applicare automaticamente, ma è possibile impedire i check-in a meno che non siano presenti i file di origine del documento e quindi decidere se è accettabile in una fase di revisione del 'codice'. Solo quelle aggiunte che passano vengono quindi incorporate nel bagagliaio (assumendo che tutti aggiungano i loro contributi a un ramo).

Troppi sviluppatori pensano che il codice sia tutto ciò che conta. Non lo è, e per una biblioteca è probabilmente la minima parte del tutto. Ottieni la documentazione, con esempi di utilizzo, descrizioni di chiamate e parametri e otterrai una migliore adozione e risparmierai molto tempo agli utenti della tua libreria. (sì, e il suo noioso da fare, ma troppo male - fallo correttamente)

    
risposta data 15.02.2012 - 00:25
fonte

Leggi altre domande sui tag