Como documentar en programacin

Breve introduccin
A continuacin de este pequeo manual se explicara una
metodologa de como documentar el cdigo fuente, que
aunque al principio supondr que es para C++, esto es
lgicamente extensible a cualquier otro lenguaje de
programacin que se fuese a utilizar.
Objetivos finales de la documentacin dentro del cdigo
fuente sern:
Que el cdigo quede documentado de modo que lean,
mantenga, reparen, etc. el cdigo lo entiendan.
Poder
extraer
de
manera
automatizada
la
documentacin, en formato leble, como HTML, PDF,
CHM, etc.
Que documentar sea una tarea fcil, y que no suponga
un sobreesfuerzo, ms all de lo estrictamente
necesario.
Ejemplo:
En breve se mostrara un cdigo fuente sin documentar

De seguido otra capture con el cdigo ya documentado

Para explicarles mejor y sin tanto rodeos les dare una breve
explicacin sobre la sintaxis bsica que se debe utilizar para
documentar siempre en cualquier programa, que se utilice en
el futuro para progamar, ya que es de mayor importancia
resaltar y dejar comentarios sobre todos los cdigos que se
generen mientras se est programando.
Les explicare por pasos breves
1. Todo comentario debe empezar por /**, y terminar en */.
2. Los documentos (con /** */) deben situarse en la lnea
inmediata superior a lo que queremos documentar ( a
veces la gente pone comentarios a la derecha de un

3.

atributo, lo cual documentaria el siguiente atributo, y no

el de la lnea actual).
Lo primero dentro de un comentario debe ser la
descripcin textual de lo que estamos documentando,
luego (dependiendo de lo que estamos documentando
(un atributo, un mtodo, una clase,)) pueden venir los
siguientes campos:
@param xxx yyy esto documenta un parmetro (xxx)
con una descripcin (yyy).
@return yyy documenta el valor retornado (yyy) por el
mtodo (o funcin).
@note xxx este comando sirve para poner notas (xxx) o
comentarios.
@warning indica alertas (xxx) o posibles problemas,
especialmente til cuando documentamos un mtodo
que dado un parmetro invalido puede causar un error
grave
@author xxx este comando indicara quien (xxx) es el
autor
@date xxx seala fechas, donde xxx suele ser una fecha
seguida de una descripcin de que se ha hecho en dicha
fecha, con esto podemos hacer listas de cambios,
poniendo sucesivas llamadas a este comando.

Con estas tres sencillas reglas ya podemos documentar casi

cualquier cosa.
Les mostrare un pequeo ejemplo de cmo documentar una
clase fecha
/** Esta clase da soporte al uso de fechas. */
class Fecha
{
// Atributos privados.
private:
/** Nmero de milisegundos desde el ao cero. */
i64 fecha;

// Mtodos pblicos.
public:
/** Constructor. */
Fecha ();
/** Constructor de copia.
@param objeto Objeto a copiar. */
Fecha (const Fecha &objeto);
/** Destructor. */
virtual ~Fecha ();
/** Establece la fecha a partir de sus subelementos.
@param anyos Aos a copiar.
@param meses Meses a copiar (0 por defecto).
@param dias Dias a copiar (0 por defecto).
@param horas Horas a copiar (0 por defecto).
@param minutos Minutos a copiar (0 por defecto).
@param segundos Segundos a copiar (0 por defecto).
@param milisegundos Milisegundos a copiar (0 por defecto).
@return Devuelve una referencia a este objeto. */
Fecha &Set (i32 anyos,
i32 meses = 0,
i32 dias = 0,
i32 horas = 0,
i32 minutos = 0,
i32 segundos = 0,
i32 milisegundos = 0);
/** Devuelve una cadena de texto con la descripcin
de la fecha.
@return Devuelve una cadena de texto con la
descripcin de la fecha. */
const i8 *GetDescripcion () const;
};