Cosa devo includere nell'intestazione della documentazione della mia classe

13

Sto cercando un formato di documentazione informativo per le classi Entity, Business Logic e Data Access.

Ho trovato i 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:
//
//==================================

Sento che seguire sono gli elementi di base

Autore
Data di Creazione
Descrizione
Cronologia delle revisioni

come spazio dei nomi e nome della classe saranno comunque presenti.

Per favore fatemi sapere cosa ne pensate, quale formato è raccomandato e se esiste un modo standard di scrivere la cronologia delle revisioni?

c# documentation comments

— CoderHawk
fonte

8

A mio avviso, la cronologia delle revisioni se si utilizza una qualche forma di VCS è già curata. Inserendolo qui aggiunge un altro posto che è necessario ricordare di documentare, perché non lasciare che VCS lo faccia per te e mantenere la documentazione del codice il più concisa possibile.

— Chris,

5

L'autore e la data di creazione sono anche gestiti dal controllo del codice sorgente. Tutto ciò che serve è una descrizione.

— Mike Seymour,

26

La maggior parte delle informazioni che hai suggerito sarebbero state trovate nel repository di origine.

L'unica cosa di cui hai veramente bisogno è la sezione scopo, 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 fosse 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 sul file corrente e visualizzare il registro di repoistory per il file, quindi non è una 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'è una possibilità che ti possa mentire. Il repository del codice sorgente conserva automaticamente questi dati storici, quindi non necessita di manutenzione e sarà accurato.

— David_001
fonte

14

Hanno nomi descrittivi di classi, metodi e variabili . 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é ne descriva chiaramente lo scopo. Sono solo note che sono assolutamente vitali e aiutano la comprensione del codice in un modo specifico. Quando si apportano modifiche al codice, i programmatori spesso dimenticano di aggiornare i commenti. Puoi finire con commenti e codice non sincronizzati e che fanno più male che bene.

Leggi questo articolo di Jeff Atwood - Coding Without Comments .

— ysolik
fonte

Voterei questa risposta +100 se potessi.

— Chris Holmes,

5

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

Non ho mai messo informazioni che non appartengono alla classe. Autore, dati, revisioni sono dati da archiviare in un sistema di controllo versione.

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

— Maniero
fonte

3

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

— Martijn Verburg
fonte

@karianna - Quindi stai suggerendo di lasciare tutto tranne la descrizione della classe nel repository di controllo del codice sorgente; ma sarà noioso vederlo ogni volta dal registro del repository. E se volessi creare un file di documentazione (come .chm o sandcastle)?

— CoderHawk,

@Sandy Dovresti essere in grado di inserire alcune parole chiave nell'intestazione del commento del codice che il tuo repository di controllo del codice sorgente aggiornerà ogni volta che effettui il check-in. Dipende dalla lingua che stai codificando e dal repository di controllo del codice sorgente che stai utilizzando. Che cosa stai usando? :)

— Martijn Verburg,

@karianna - Sto usando Subversion; spero che discutere di poca tecnologia / programmazione non lo faccia chiudere! :-) Per favore fatemi sapere se devo pubblicare una domanda in SO chiedendo come unire il commento del registro a una particolare classe? :-)

— CoderHawk,

Puoi usare $ Id: $ e $ URL: $, il: potrebbe essere facoltativo, ho dimenticato. Spero che i signori SO non ci uccideranno per la nostra bestemmia

— Martijn Verburg,

3

Tutto in quell'elenco 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 hai nominata male o (b) hai scritto una cattiva classe che sta facendo troppo (SRP).

— Chris Holmes
fonte

2

Ho provato a cambiare i miei modelli di intestazione poiché, come altri sottolineano, molte di queste informazioni possono essere trovate 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 - Eventuali riferimenti da cui dipende il codice non sono chiari tramite l'uso di includeistruzioni simili.

Un elemento che può anche essere utile includere è una sezione sulle parole chiave Mentre potresti essere in grado di fare una ricerca per nomi di funzioni, classi, strutture, ecc., Ci potrebbero essere alcune parole chiave che gli altri nomi nel file non chiariscono. O per un codice meno recente e scarsamente documentato, potrebbe essere il primo passo per documentare il codice per la manutenzione.

— rjzii
fonte

1

La maggior parte delle altre risposte che ho letto finora presupponeva che esistesse solo un repository sempre disponibile

Dato che il codice sorgente può perdere la connessione al repository (cioè se copiato) la mia documentazione di classe va così:

class documentation header (= il blocco dei commenti all'inizio del file) contiene solo le informazioni legali richieste (ovvero copyright di xyz su licenza gpl)
tutto ciò che uno sviluppatore che utilizza la classe dovrebbe sapere dovrebbe entrare nei commenti di classe java-doc (o l'equivalente .net) in modo che gli ide-moderni possano mostrare queste informazioni come informazioni di tooltip nel codice sorgente che utilizza la classe.

Puoi anche aggiungere il numero del ticket per il bugfix o la richiesta di funzionalità in modo da avere qualche indizio su dove / quando / perché la classe è stata creata (se sei abbastanza fortunato da poter ancora accedere ai biglietti dopo qualche anno).

Quando è stato chiesto di risolvere i problemi nei vecchi programmi legacy a sorgente chiuso, i numeri dei biglietti erano abbastanza preziosi per me per comprendere i requisiti originali del codice.

— k3b
fonte