DOCUMENTACION EN LA ETAPA DE CODIFICACION

Héctor Javier Abril Bringas

Introducción

Existen dos tipos de documentación de software: externa e interna. La documentación externa, como por ejemplo las especificaciones, los archivos de ayuda y los documentos de diseño, se mantiene fuera del código fuente. La documentación interna está formada por los comentarios que los programadores escriben dentro del código fuente durante la fase de desarrollo.

Pese a la disponibilidad de la documentación externa, debe contarse con listados independientes del código fuente, por si se perdiera la documentación de recuperación impresa. La documentación externa puede constar de especificaciones, documentos de diseño, peticiones de cambios, historial de errores y el estándar de codificación empleado.

Uno de los problemas de la documentación de software interna es garantizar que se mantienen y actualizan los comentarios al mismo tiempo que el código fuente. Aunque unos buenos comentarios en el código fuente no tienen ningún valor en el tiempo de ejecución, resultan valiosísimos para un programador que tenga que mantener una parte de software particularmente intrincada o compleja.

En la programación de computadoras, un comentario es una construcción del lenguaje de programación destinada a integrar información adicional en el código fuente de un programa. En la mayoría de los casos, cuando el código fuente es procesado por un compilador o intérprete, los comentarios no se toman en cuenta.

Los comentarios tienen una amplia gama de posibles usos: desde la mejora del código fuente con descripciones básicas hasta la generación de documentación externa. También se utilizan para la integración con sistemas de control de versiones y otros tipos de herramientas de programación externas.

La flexibilidad proporcionada por los comentarios da pie a un amplio abanico de formas de uso distintas y a la inclusión de información inútil dentro del código fuente. Para evitar este inconveniente, muchos programadores y analistas de software recomiendan adoptar "filosofías" o metodologías para la correcta utilización de los comentarios.

Información general

El código fuente se puede dividir conceptualmente en código fuente (consistente en instrucciones inteligibles por la computadora) y comentarios (que consisten en notas inteligibles por el ser humano, además de ciertas anotaciones para dar soporte al código fuente). Las reglas y sintaxis de ambos están descritas en la especificación del lenguaje de programación.

Los comentarios adoptan por norma general un formato o bien de "bloque" (también denominado de "prólogo") o bien de "línea" (también denominado "inline") .

Un comentario de bloque delimita una zona del código fuente compuesta por varias líneas de texto. Esta región se reconoce por un delimitador de inicio y un delimitador de final del comentario. Algunos lenguajes de programación admiten que los comentarios se aniden unos dentro de otros (e.g., MATLAB), pero otros lenguajes (e.g., Java) no lo admiten.

Un comentario de línea comienza con un delimitador y continúa hasta el final de la línea de texto (es decir, no es necesario un segundo delimitador). En algunos lenguajes, el comentario de línea siempre comienza en una cierta columna no siendo necesario un delimitador.

Los delimitadores son una secuencia conocida de caracteres y suelen ser distintos para los comentarios de bloque que para los de línea. Por ejemplo, el lenguaje C++ usa los delimitadores /* y */ para los comentarios de bloque mientras que los comentarios de línea utilizan el delimitador //. Otros lenguajes solamente admiten un tipo de comentario. Por ejemplo, ADA solamente dispone de comentarios de línea mediante el delimitador --.

Usos:

Descripción de código Los comentarios pueden ser utilizados para resumir el código o para explicar la intención del programador. Según esta escuela de pensamiento, la necesidad de volver a explicar el código puede ser un signo de que es demasiado complejo y debe ser reescrito.Los comentarios también pueden ser utilizados para explicar por qué un bloque de código no se ajusta a las convenciones o las buenas prácticas. Esto es especialmente relacionado con ciertos proyectos de escaso tiempo de desarrollo, o en la corrección de errores.

Usos

Descripción algorítmica

A veces, el código fuente contiene una solución a un problema digno de mención específica. En tales casos, los comentarios pueden contener una explicación de la metodología.Estas explicaciones pueden incluir diagramas y pruebas matemáticas formales. Esto puede ser la explicación del código, en lugar de una clarificación de sus intenciones, pero en la tarea de mantener la base del código se puede encontrar esta explicación fundamental.Por ejemplo, un programador puede agregar un comentario para explicar por qué un tipo de inserción fue elegido en lugar de una ordenación rápida, pues la primera es, en teoría, más lento que el segundo sin embargo puede que en el ejemplo no se esta buscando rendimiento sino estabilidad.

Inclusión de recursos

Diagramas y otros tipos de herramientas de ayuda gráfica pueden ser insertadas en el código fuente en forma de comentario. Además, los avisos de derechos de autor, fecha de creación, versión del producto, contacto con el propietario y/o creador, etc. puede ser embebido en código fuente como comentarios.

Debugging Una práctica común es comentar un fragmento de código, de

modo que no se ejecutará en el programa final, pero si da una idea de que se podría o se quiso haber hecho en el programa, a veces también es usado para dejar las bases de una nueva versión del software.

Generación de documentación Las herramientas de programación en ocasiones incorporan

documentación y metadatos en los comentarios. Estas pueden incluir las posiciones de inserción para la inclusión automática de cabecera del archivo, los comandos para configurar el modo de resaltar el archivo de sintaxis o el número de revisión del archivo. Estos comentarios son el control funcional también conocido comúnmente como anotaciones. Mantener la documentación de comentarios del código fuente se considera como una forma de simplificar el proceso de documentación, así como aumentar las posibilidades de que la documentación se mantendrá al día con los cambios en el código.

Normalmente este tipos de comentarios conlleva a utilizar una sintaxis básica para que puedan ser interpretados por el generador de documentación a diferencia de los comentarios anteriores donde no necesariamente se debe de utilizar una sintaxis predefinida.

C# y Visual Basic implementan una característica similar llamada comentarios XML, que son leídos por IntelliSense.

Estilos

Hay muchas alternativas cuando se considera como los comentarios deben aparecer en el código fuente. Para grandes proyectos, los estilos de los comentarios se agregan apenas comienzan el proyecto. Normalmente los programadores prefieren estilos que son consistentes, no obstructivos, fáciles de modificar, y difíciles de romper.

Los siguientes fragmentos de codigo en C son solo un ejemplo de como los comentarios pueden variar de estilo, mientras todos contienen la misma información básica:/* Este es el cuerpo del comentario.Variante 1 */ /***********************************\ * * * Este es el cuerpo del comentario. * * Variante 2. * * * \************************************/

Etiquetas

Algunas etiquetas se utilizan en los comentarios para ayudar en la indexación de los problemas comunes. Tales etiquetas son comúnmente resaltado de sintaxis y permite búsquedas con herramientas de programación común, como la utilidad grep de UNIX. Ejemplos de convenios etiqueta son:FIXME: para marcar código problemático potencial que requiere una atención especial y/o revisión.

NOTE: peligros potenciales para documentar el funcionamiento interno del código y de indicar.

TODO: para indicar las mejoras planificadas.

XXX: para advertir a otros programadores de código problemático o equivoco.Existe el riesgo de que las etiquetas se acumulan con el tiempo, es conveniente incluir la fecha y el propietario de etiqueta en el comentario de etiquetas para facilitar el seguimiento

Documentando el codigo

La documentación comienza con la elección de los nombres de los identificadores(variables y etiquetas), continúa con la localización y composición de los comentarios y termina con la organización visual del programa.

La elección de nombres de identificadores significativos es crucial para la legibilidad. Los lenguajes que limitan la longitud de los nombres de las variables o de las etiquetas a unos pocos caracteres, implícitamente limitan la comprensión. Considere las siguientes sentencias:

D=V * T

DIST= VELHOR * TIEMPO

DISTANCIA=VELOCIDAD.HORIZONTAL * TIEMPO TRANSCURRIDO EN SEG.

La posibilidad de expresar los comentarios en el lenguaje natural como parte del listado de código fuente es algo que aparece en todos los lenguajes de programación de propósito general. Sin embargo surgen ciertas preguntas: 

 ¿Cuántos comentarios son "suficientes"?  ¿Dónde se deben situar los comentarios?  ¿Oscurecen los comentarios la lógica del programa?  ¿Pueden los comentarios distraer al lector?  ¿Son los comentarios "no mantenibles", y por lo tanto, no fiables?

Hay pocas respuestas definitivas a las preguntas anteriores.Pero una esta muy clara: El software debe contener documentación interna.

Los comentarios de prólogo y los comentarios descriptivos son dos categorías que requieren un enfoque diferente. Al principio de cada módulo, debe haber un comentario de prólogo. El formato para estos comentarios es el siguiente:

Una sentencia de propósito que indique la función del módulo. Una descripción de la interfaz que incluya:

Un ejemplo de la "secuencia de llamada" Una descripción de todos los argumentos. Una lista de todos los módulos subordinados.

Una explicación de los datos pertinentes, tales como las variables importantes y su uso, de las restricciones y de las limitaciones y de otra información importante.

Una historia del desarrollo que incluya: El diseñador del módulo(autor). El revisor(auditor) y fecha. Fechas de modificación y descripción.

Comentarios descriptivos.

Los comentarios descriptivos se incluyen en el cuerpo del código fuente y se usan para  describir las funciones del procesamiento. "los comentarios deben proporcionar algún extra no solamente parafrasear el código"Además los comentarios descriptivos deben:

Describir los bloques de código en vez de describir cada línea. Usar líneas en blanco o tabulaciones de forma que sean

fácilmente distinguibles del código. Que sean correctos, un comentario incorrecto o que se pueda

interpretar mal es peor que no ponerlo.

Con unos recursos nemotécticos apropiados para los identificadores y unos buenos comentarios se asegura una documentación interna adecuada.

Cuando se representa un diseño de procedimientos detallado mediante un lenguaje de diseño de programas, se puede incluir directamente la documentación del diseño en el listado fuente como sentencias de comentario. Esta técnica es particularmente útil cuando la implementación se lleva a cabo en lenguaje ensamblador y ayuda a asegurar que, tanto el código como el diseño, podrán fácilmente mantenerse al hacer cambios sobre ellos.

El sangrado del código fuente realza las construcciones lógicas y los bloques de código, tabulando desde el margen izquierdo de forma que se vean desplazados estos atributos.  

Técnicas de comentarios recomendadas

Si programa en C#, utilice la función de documentación XML. Para obtener más información, vea Documentación XML.

Cuando modifique el código, mantenga siempre actualizados los comentarios circundantes.

Al principio de cada rutina, resulta útil hacer comentarios estándar, repetitivos, que indiquen el propósito de la rutina, las suposiciones y las limitaciones. Un comentario repetitivo podría consistir en una breve introducción que explicara por qué existe y qué puede hacer.

Evite añadir comentarios al final de una línea de código, porque lo hacen más difícil de leer. Sin embargo, los comentarios de final de línea sí son apropiados al anotar declaraciones de variables. En este caso, alinee todos los comentarios de final de línea en la misma posición de tabulación.

Evite los comentarios recargados, como las líneas enteras de asteriscos. En su lugar, utilice espacios para separar los comentarios y el código.

Evite rodear un bloque de comentarios con un marco tipográfico. Puede resultar agradable, pero es difícil de mantener.

Antes de la implementación, quite todos los comentarios temporales o innecesarios, para evitar cualquier confusión en la futura fase de mantenimiento.

Si necesita realizar comentarios para explicar una sección de código compleja, examine el código para decidir si debería volver a escribirlo. Siempre que sea posible, no documente un código malo, vuelva a escribirlo. Aunque, por regla general, no debe sacrificarse el rendimiento para hacer un código más simple para el usuario, es indispensable un equilibrio entre rendimiento y mantenibilidad.

Use frases completas cuando escriba comentarios. Los comentarios deben aclarar el código, no añadirle ambigüedad.

Vaya comentando al mismo tiempo que programa, porque probablemente no tenga tiempo de hacerlo más tarde. Por otro lado, aunque tuviera oportunidad de revisar el código que ha escrito, lo que parece obvio hoy es posible que seis semanas después no lo sea.

Evite comentarios superfluos o inapropiados, como comentarios divertidos al margen.

Use los comentarios para explicar el propósito del código. No los use como si fueran traducciones interlineales.

Comente cualquier cosa que no sea legible de forma obvia en el código.

Ejemplos

Ensamblador ;comentario

Java //comentario de linea/*comentario de bloque*//**comentario que sera usado por javadoc*/

C/C++ //comentario en linea/* comentario en bloque*/

Ruby #comentario

Python #comentario

Perl #comentario

Javascript En archivo .js pueden darse las siguientes formas://comentario en linea/* comentarioen bloque */En las páginas webs , aparte de las anteriores formas también está el

comentario HTML:<!-- sentencias javascript no obviadas // -->

SQL //esto es un comentario--este también/* y esteen bloque */

Visual Basic 'comentario'''comentario XML

PHP //comentario en linea#este también/* comentarioen bloque */

Software para documentar:

Java: javadoc.

D: Ddoc.

C/C++, Java: doxygen.

PHP: IDL, PHPDoc.

Bibliografía

Comentarios http://msdn.microsoft.com/es-es/library/aa291593(VS.71).aspx

Comentarios http://es.wikipedia.org/wiki/Comentario_(informática)

Documentación de codigo http://148.202.148.5/cursos/cc321/fundamentos/unidad5/tema5_2

.html

Code Documentation Tutorial http://wikkawiki.org/DocumentingCodeHowto