Estilo de los comentarios

Publicado en Lenguajes, Peticiones el 9 de January, 2009 por Fran.

Desde hace tiempo vengo pensando en cómo comenta la gente, ya que mi empresa es muy pequeña y no puedo hacerme una idea del mundo real. Con cómo comentáis me refiero a si usáis algún tipo de sintaxis/estilo de comentarios tipo JavaDoc o similar.

En mi caso, mi estilo siempre había sido colocar al principio del archivo y antes de la función el nombre de éste/a y una pequeña descripción de lo que te vas a encontrar en él/ella. Pero normalmente la descripción de las funciones se me quedaba un poco corta, hay que aclarar que suelo programar en C, así que decidí pasarme a la sintaxis de JavaDoc que ya la conocía de mi PFC (que hice en Java).

Lo malo es que al programar en C, lo único que me vale de JavaDoc es su sintaxis, ya que la generación de la documentación de la API no la puedo realizar. Así que busqué, y encontré Doxygen (lo usan en KDE), pero la verdad es que lo he probado un poco y no me acaba de convencer, lo bueno es que puedo mantener la sintaxis de JavaDoc, pero la documentación que genera no me gusta.

Así que os pregunto, ¿usáis algún tipo de sintaxis especial para los comentarios? Si es así, ¿cuál? y ¿por qué? Y para terminar, ¿usáis alguna herramienta de generación de documentación a partir de los comentarios? Si es así, ¿cuál? y ¿por qué?

3 comentarios

  1. Uno de los estilos de documentación que he usado y me ha gustado bastante, ha sido natural docs, principalmente porque es una forma clara y simple de documentar, sin información innecesaria adicional, solo texto en claro. Además, es multilenguaje, algo realmente importante a tener en cuenta en según que ámbitos.

    #  blaxter 9 de January, 2009

  2. Nosotros utilizamos Doxygen. En nuestro proyecto (http://Osmius.net) tenemos mucho código C++ y también Java, así que con una sintaxis parecida generamos para las dos partes.

    Puedes echar un vistazo aquí:
    http://www.osmius.net/doxygen/html/index.html

    #  Joselu 10 de January, 2009

  3. En nuestro caso, Javadoc; pero claro, nosotros programamos en Java :D

    Para lo poco que hacemos en Delphi encontramos PasDoc, que te deja casi el mismo formato.

    #  Lek 12 de January, 2009

Escribe un comentario