Quanto è complessa la documentazione che scrivi? [chiuso]

Lavorando su PHP e NetBeans, lo stile della documentazione è praticamente PHPDoc. Così scrivo un po 'di più di ciò che genera l'IDE.

es. IDE genera:

/**  
 * Description for ClassA  
 *  
 *  
 * @author Sam-Mauris Yong  
 */  

class ClassA{

    function __construct(){
        echo "5";
    }

}

Probabilmente scriverò:

/**  
 * Class A Helper Class
 * Some example class used here
 *  
 * @author Sam-Mauris Yong
 * @license GNU Public License v3
 */  

class ClassA{

    /**
     * Constructor for example class
     * echos 5
     */
    function __construct(){
        echo "5";
    }

}

Seguo questa convenzione:

//-----------------------------------------------------------------------------
// MPlayer_PlayAlbum
//
// PURPOSE:
//  Creates a playback selection of the given album and starts playing it
//
// PARAMETERS:
//  int AlbumId  [in] Zero based index of the album to playback,
//                    or -1 to playback all the albums (not for iPod)
//  int ArtistId [in] Zero based ID of the artist, or -1 if AlbumId is from the
//                    global enumeration of albums; if AlbumId is -1 this
//                    parameter is ignored
//  int TrackId  [in] Zero based index of the track representing the first item
//                    to play; if AlbumId is -1 this parameter is ignored
//
// RETURNS:
//  ERROR_SUCCESS if the function succeeds
//  ERROR_UNINITIALIZED if the remote control is not initialized
//  ERROR_INVALID_PARAMETER if one ore more parameters are not correct
//  ERROR_DEVICE_NOT_AVAILABLE if no device is present
//  ERROR_DEVICE_IN_USE if it's currently impossible to use the device remotely
//-----------------------------------------------------------------------------
DWORD WINAPI MPlayer_PlayAlbum(int AlbumId, int ArtistId, int TrackId);

Evito di aggiungere il nome dell'autore come controllo del codice sorgente già a tracciare l'autore e i contributori originali.

Tendo a scrivere documentazione come questa:

Method name(method signature)

Questo è method . Ecco una spiegazione di alto livello di ciò che fa.

Ecco cosa rappresenta param 1.

Ecco cosa rappresenta param 2.

... etc.

Ecco cosa farà se passerai dati non validi nei parametri.

Vedi anche:

Method's class
Related method
Other related method

Dipende da alcune cose:

• formalismo di codice. codice che altre persone ottengono un pettine più fine rispetto al codice personale
• tecnicità del codice

Di norma, tutte le funzioni non banali ricevono una riga che dice quello che fanno.

All'altra estremità:

//funcname
//purpose
//params and their meaning
//description incl. weirdnesses
//exceptions that might show up
//maintainer notes
//future todos

Inoltre alcuni delimitatori come /////////////////////////////////// o what-have-you.

Credo fermamente che il 90% + del tempo, il codice dovrebbe essere auto-documentante, IOW, nomi di variabili, nomi di metodi e nomi di classi dovrebbero chiaramente raccontare la storia di ciò che sta accadendo. Solo in rari casi in cui devo fare qualcosa di inaspettato (iterando attraverso una raccolta e minuscole i valori) documenterò PERCHÉ lo sto facendo (non COSA sto facendo).

Ho una base di codice di linea approssimativa di 500K e scommetto che ci sono meno di 30 righe di commenti nell'intera cosa ed è (soprattutto) chiaro che cosa sta facendo il codice e perché. Trovo che sto principalmente documentando su API esterne.

Dipende dal tipo di lavoro che stai facendo, da come viene eseguito, con quale approccio SDLC e le dimensioni del team.

In un gruppo in cui lavoro, la documentazione è un'entità desiderata con nomi variabili di 1-3 lettere ciascuno. Metà del tempo i nomi delle classi sono 1-3 lettere ciascuno o un "gestore". Il mio codice è il più possibile auto-documentabile con un doc di parole di 2-3 pagine su come dovrebbe essere usato.

Nell'altro gruppo in cui lavoro è un progetto a cascata. Scriviamo 30-40 pagine di documenti per ogni livello (questo ultimo documento che ho scritto completo di diagrammi, tabelle e figure era di 60 pagine.) Ci sono 3 fasi primarie prima che il codice sia scritto e in ogni fase c'è una specifica, una preliminare, una lista di controllo, un documento formale, un foglio di calcolo della matrice di verifica e una revisione.

Spero che ti aiuti.