Comenta y documenta tu código

Publicado el jue 21 agosto 2008

Hace algunos años, en un ramo de la universidad, me exigían comentar el código fuente. a medida que comentaba el código me di cuenta que la única utilidad posible de ésto era que otro programados entendiera que hace o como lo hace viendo directamente el código y el comentario, algo muy limitado.
Fue en ese punto cuando conocí la documentación de código fuente, un elemento que lleva los comentarios un paso más allá. Consiste en emplear tags o docstring (dentro de un bloque o línea de comentario) para generar documentos que incluyen entro otros las clases, atributos, métodos, funciones y paquetes.

Python, mediante epydoc podemos emplear varias sintaxis para documentar el código, a continuación les dejo la sintaxis restructuredtext que es la ecolución de epytext. Permite exportar los documentos a html, pdf, latex.

class prueba   
    '''Esta es una clase de prueba

    Las clases de prueba se emplean para ejemplificar alguna cosa.

    :ivar algo: Es una variable de la instancia
    :type algo: bool

    '''

    def __init__(self, entrada):
        '''Este es el constructor

        :param entrada: Es un parámetro de entrada
        :type entrada: str

        '''
        self.algo = entrada

    def funcionUno(self):
        '''Este método hace algo

        :return: Retorna un hola
        :rtype: str

        '''
        return 'hola'

Para generar la documentación debemos ejecutar el siguiente comando:

epydoc path/hasta/fuente -o path/salida/

esto generará la documentación como html, podemos agregar --pdf, --latex, --ps, --dvi para otros formatos.
Actualmente existen herramientas que permiten documentar código en casi cualquier lenguaje.