Il campo deve avere un colpo di testa di documentazione - Stile Cop - odore di codice?

Question

Stavo correndo stile poliziotto contro alcuni del mio codice e ottenuto alcuni:

SA1600: The field must have a documentation header.

Ora non fraintendetemi mi piace lo stile poliziotto, è grande quando si lavora su un progetto con più di una persona, ma questa regola sembra un po 'eccessivo per me. Perché si vuole aggiungere:

    /// <summary>
    /// blah blah blah
    /// </summary>

alla parte superiore di ogni variabile. Sono abbastanza sicuro che mi ricordo qualcuno dicendo (Martin Fowler, Kent Beck..can't mi ricordo ATM) che il commento dovrebbe dire "perché" non "cosa" e non posso davvero vedere come si può spiegare il motivo per cui su un variabile.

Trovo anche il codice che ha commenti su ogni variabile più difficile da leggere perché tutto quello che vedi è fluff.

I miei pensieri sono se si deve spiegare ciò che ogni variabile è allora siete veramente fallendo in termini di denominazione.

Qualcun altro trovare commentando variabili un po 'di un odore di codice o è solo a me.

Answer 1

Non direi che commentando una variabile è sempre un codice odore (e non suona come questo è quello che stai dicendo, o). Sono d'accordo che commentando ogni singola variabile, ogni volta è per lo meno eccessivo, e forse indicativi di scarsa denominazione. In effetti, alcuni sostengono che qualsiasi commento è un odore di codice, e che i nomi descrittivi e le routine brevi sono più leggibili e prevenire la situazione in cui il codice è stato modificato, ma i commenti non sono stati aggiornati ( che mi ha certamente morso in poche basi di codice legacy). Non credo che mi piacerebbe portarlo a tanto, ma se è possibile scrivere codice che si spiega da sé senza spiegazioni in più, che sembra preferibile.

Quindi sì, in pratica quello che hai detto.

Answer 2

Questo è piuttosto un vecchio post, ma è venuto attraverso di esso durante la ricerca di una soluzione a questo problema me stesso, così anche se mi piacerebbe offrire una soluzione.

Se si apre il Settings.StyleCop file nell'editor regole, selezionare Regole Documentazione il nodo, quindi nella sezione Impostazioni dettagliate su il diritto de-selezionare il campi sono . Ora non sarà più richiesto di documentare i campi.

Answer 3

XML Commenti sono leggermente diverse rispetto ad altri commenti.

Se si imposta le cose in modo corretto, è possibile farle apparire con descrizioni dei comandi in Visual Studio e li usa per creare MSDN documentazione stile con il castello di sabbia. Credo che dovrebbero dirti quello che il coso sta facendo quando non si ha accesso al codice sorgente.

Il punto è che questi commenti possono apparire senza il codice sorgente che stanno commentando. Dovrebbero essere utile ad un altro devloper che non può vedere il tuo codice e potrebbe fregare di meno come si sta facendo le cose.

Non so circa la funzione "Cop" che si sta utilizzando, ma sarebbe bello avere un modo di segnalare lo strumento che intende lasciare un vuoto param. Quindi:

    /// <param name="fubar"></param>  // Haven't gotten around to it
    /// <param name="portNumber" />   // I intend this parameter to have no help

Ho lavorato su progetti in cui dobbiamo compilare tutto in e noi ottenere le cose come:

    /// <param name="portNumber">The Port Number</param> // What else could it be?

Se non si desidera utilizzare le funzioni di cui sopra, andare avanti disattivare la regola di stile Cop.

Answer 4

Totalmente d'accordo e la prima cosa che ho spento in StyleCop. Se avete bisogno di spiegarlo, è stato chiamato in un modo che ha bisogno di spiegazione e non sono riusciti a rendere il codice auto documentazione .

Answer 5

Per coloro che ancora venire attraverso questo problema, questo post how-to dal cambiamento a-StyleCop-regola in realtà ha la risposta perfetta.

Answer 6

Si dovrebbe cercare GhosDoc è un modo semplice per avere una documentazione automatizzata per ogni membro codice su la tua applicazione. Basta installarlo, fare clic destro sul membro e selezionare il documento questo!

Answer 7

Credo che la risposta corretta qui è "dipende". Si può certamente spiegare la statica / const "perché" di una variabile essere contrassegnato, o la logica di business / restrizioni sul contenuto della variabile. Detto questo, sono d'accordo che vedere ogni commento variabile impedisce la leggibilità e può indicare ciecamente a seguito di una denominazione standard o improprio.