¿Qué tan compleja es la documentación que escribe? [cerrado

Question

En un libro que estoy leyendo hay un capítulo sobre documentación para su código. El libro trata sobre PHP y describe algunos métodos fáciles, pero también para obtener algunos métodos complicados y que consumen mucho tiempo (XML, XSL) como Docbook.

En mi pequeña empresa actual (5 personas) incluso rara vez escribimos comentarios, pero me pregunto si en una gran empresa, ¿cuán detallada escriben? ¿Utilizan herramientas como Docbook? ¿Es complejo o simple?

Answer 1

Trabajando en PHP y NetBeans, el estilo de documentación es prácticamente PHPDOC. Por lo tanto, escribo un poco más de lo que genera el IDE.

EG IDE genera:

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

class ClassA{

    function __construct(){
        echo "5";
    }

}

Probablemente escribiré:

/**  
 * 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";
    }

}

Answer 2

Sigo esta convención:

//-----------------------------------------------------------------------------
// 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 agregar el nombre del autor como control de origen que ya se ocupa del trazado de autor original y contribuyentes.

Answer 3

Tiendo a escribir documentación como esta:

Method name(method signature)

Esto es method. Aquí hay una explicación de alto nivel de lo que hace.

Esto es lo que representa Param 1.

Esto es lo que representa Param 2.

...etc.

Esto es lo que hará si los pasa datos no válidos en los parámetros.

Ver también:

Method's class
Related method
Other related method

Answer 4

Depende de algunas cosas:

• Formalismo del código. código que otras personas obtienen un peine más fino que el código personal
• tecnicismo del código

Como regla general, todas las funciones no triviales obtienen una línea que dice lo que hacen.

En el otro extremo:

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

Además de algunos delimitadores como /////////////////////////////////// o lo que tienes que tú.

Answer 5

Creo firmemente que el 90%+ del tiempo, el código debe ser autopogado, IOW, nombres de variables, nombres de métodos y nombres de clase debería contar claramente la historia de lo que está sucediendo. Solo en casos raros cuando tenga que hacer algo algo inesperado (iterando a través de una colección y más bajo los valores) documentaré por qué lo estoy haciendo (no lo que estoy haciendo).

Tengo una base de código de línea de aproximadamente 500k y apuesto a que hay menos de 30 líneas de comentarios en todo y (sobre todo) está claro qué está haciendo el código y por qué. Me parece que estoy documentando principalmente en las API externas.

Answer 6

Depende del tipo de trabajo que esté haciendo, cómo se ejecuta, con el cual SDLC se acerca y el tamaño del equipo.

En un grupo donde trabajo, la documentación es una entidad deseada con nombres variables de 1-3 letras cada una. La mitad del tiempo los nombres de la clase son 1-3 letras cada uno o un "controlador". Mi propio código es posible autodocumentar con un documento de palabras de aproximadamente 2-3 páginas sobre cómo debe usarse.

En el otro grupo donde trabajo es un proyecto de cascada. Escribimos 30-40 páginas en documentos para cada etapa (este último documento que escribí completo con diagramas, tablas y cifras fue de 60 páginas). Hay 3 etapas principales antes de que el código se escriba y en cada etapa hay una especificación, una Preliminar, una lista de verificación, un documento formal, una hoja de cálculo de verificación matriz y una revisión.

Espero que ayude.