it-swarm-es.com

¿Qué tan complejo es la documentación que escribes?

En un libro que estoy leyendo, hay un capítulo sobre la documentación de su código. El libro es aproximadamente PHP y describe algunos métodos fáciles, pero también van a algunos métodos complicados y de consumo de 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 compañía, ¿qué documentación detallada escriben? ¿Utilizan tales herramientas como DocBook? ¿Es complejo o simple?

6
Centurion

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

p.ej. IDE GENERA:

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

class ClassA{

    function __construct(){
        echo "5";
    }

}

Probablemente escribo:

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

}
3
mauris

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 ya ocupo de rastrear el autor y los contribuyentes originales.

2
Wizard79

Tiendo a escribir la documentación de esta manera:

Method name(method signature)

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

Aquí está lo que representa Param 1.

Aquí está lo que representa Param 2.

... etc.

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

Ver también:

Method's class
Related method
Other related method
1
Mason Wheeler

Depende de algunas cosas:

  • formalismo del código. Código que otras personas obtienen un peine más fino que el código personal.
  • tECITELIDAD DE CÓDIGO

Como regla general, todas las funciones no triviales reciben 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

Más algunos delimitadores como /////////////////////////////////// o lo que tengas, tú.

1
Paul Nathan

Creo firmemente que el 90% + del tiempo, el código debe ser autocontrol, los nombres de IOW, los nombres de los métodos y los nombres de las clases deben distinguir claramente la historia de lo que está sucediendo. Solo en casos raros cuando tengo que hacer algo algo inesperado (iterando a través de una colección y una reducción de los valores), hará documentar por qué lo estoy haciendo (no lo que estoy haciendo).

Tengo una base de código de línea aproximadamente 500K y apuesto a que hay menos de 30 líneas de comentarios en todo el asunto y es (en su mayoría) claro lo que está haciendo el código y por qué. Encuentro que estoy documentando principalmente alrededor de API externas.

1
MBonig

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

En un grupo donde trabajo, la documentación es deseada por la entidad con nombres variables de 1-3 letras cada una. La mitad del tiempo los nombres de las clases son 1-3 letras cada uno o un "controlador". Mi propio código es lo más posible, automática con aproximadamente una palabra Doc de 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 de documentos para cada etapa (este último documento escribo completo con diagramas, tablas y cifras fue de 60 páginas). Hay 3 etapas primarias antes de que el código incluso se escribe y en cada etapa hay una especificación, un Preliminar, una lista de verificación, un documento formal, una hoja de cálculo de matriz de verificación y una revisión.

Espero que ayude.

1
wheaties