Cosa dovrei includere nell'intestazione della documentazione della mia classe

13

Sto cercando il formato informativo della documentazione di classe per le mie classi Entity, Business Logic e Data Access.

Ho trovato seguenti due formati da qui

Formato 1

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

Formato 2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

Ritengo che i seguenti siano gli elementi di base

  • Autore
  • Data di creazione
  • Descrizione
  • Cronologia revisioni

come lo spazio dei nomi e il nome della classe ci saranno comunque.

Fammi sapere le tue opinioni, quale formato è raccomandato e se esiste un metodo standard per scrivere la cronologia delle revisioni?

    
posta CoderHawk 06.10.2010 - 14:50
fonte

6 risposte

18

La maggior parte delle informazioni che hai suggerito potrebbero essere trovate nel repository sorgente.

L'unica cosa di cui hai veramente bisogno è la sezione degli scopi, che dice a cosa serve la classe.

Sarebbe noioso cercare nel repository ogni volta che vuoi conoscere le altre informazioni? Direi di no. Quanto spesso ti importa chi è stato l'autore originale? O quando il file è stato creato per la prima volta? I plug-in (come Ankh SVN per Visual Studio) spesso consentono di fare clic con il pulsante destro del mouse all'interno del file corrente e visualizzare il registro delle repoistorie per il file, quindi non è una gran seccatura vedere effettivamente queste informazioni.

Inoltre, se si memorizza la cronologia delle versioni in un commento, questo commento deve essere mantenuto. Quindi nel tempo c'è la possibilità che possa mentirti. Il repository del codice sorgente mantiene automaticamente questi dati storici, quindi non ha bisogno di tale manutenzione e sarà accurato.

    
risposta data 06.10.2010 - 14:56
fonte
11

Hai nomi descrittivi di classe, metodo e variabile . Ciò eliminerà la necessità di tali commenti come scopo e descrizione. A volte pensiamo che più breve è il nome del metodo, meglio è. Al contrario, crea un nome per il metodo che desideri purché descriva chiaramente il suo scopo. Solo avere note che sono assolutamente vitali e aiutare la comprensione del codice in un modo specifico. Quando si apportano modifiche al codice, i programmatori dimenticano spesso di aggiornare i commenti. Puoi finire con commenti e codice non sincronizzati e fare più male che bene.

Leggi questo articolo di Jeff Atwood - Coding senza commenti .

    
risposta data 06.10.2010 - 16:33
fonte
4

Uso tag standard per generare documentazione. Niente di più, niente di meno. Vedi qui

Non inserisco mai informazioni che non appartengono alla classe. Autore, dati, revisioni sono dati da memorizzare su un sistema di controllo versione.

I due formati presentati sono inutili per generare documentazione e hanno il più grande errore nei commenti, elencano la cronologia delle revisioni.

    
risposta data 06.10.2010 - 18:12
fonte
3

Molte di queste informazioni possono essere aggiunte dal repository di controllo del codice sorgente, lasciandovi solo una descrizione, che dovrebbe descrivere accuratamente l'ambito e il comportamento della classe. Ti consiglio di dare un'occhiata ad alcuni Javadoc per Java JDK come esempio.

    
risposta data 06.10.2010 - 14:55
fonte
2

Tutto in quella lista non è necessario. Il controllo del codice sorgente dovrebbe occuparsi di quasi tutto, e ciò che non copre è curato da buone convenzioni di denominazione.

Se devo leggere la tua "Descrizione" per capire cosa sta facendo la tua classe, allora (a) la tua chiamata male o (b) hai scritto una cattiva classe che sta facendo troppo (SRP).

    
risposta data 06.10.2010 - 18:53
fonte
1

Mi sono divertito a modificare i miei modelli di intestazione dato che, come altri sottolineano, molte di queste informazioni sono reperibili nel repository e finora i grandi campi che ho cercato di mantenere sono i seguenti :

  • Descrizione : cosa viene fatto dal codice.
  • Note : tutto ciò che deve essere conosciuto sul codice che non è facilmente derivato dai commenti nel codice stesso.
  • Riferimenti : tutti i riferimenti che dipendono dal codice non vengono resi chiari mediante l'uso di include o dichiarazioni simili.

Un elemento che potrebbe anche essere utile includere è una sezione su Parole chiave mentre potresti essere in grado di cercare nomi di funzioni, classi, struct, ecc., potrebbero esserci alcune parole chiave che altri nomi nel file non rendono chiaro. O per codice vecchio, scarsamente documentato, potrebbe essere il primo passo per documentare il codice per la manutenzione.

    
risposta data 06.10.2010 - 15:37
fonte

Leggi altre domande sui tag