NeoProgramadores - Cómo Documentar Código con Efectividad
http://www.galeon.com/neoprogramadores/howdocod.htm
Cómo Documentar Código con Efectividad Tips para la escritura de documentación interna Por J. F. Díaz (jfdiaz98@hotmail.com) Lic. en Ciencias de la Computación Aunque muchas veces es omitida por los principiantes y los que se dedican a producir resultados rápidos debido a que no es tan atractiva como la codificación, la documentación --al igual que el diseño-- es una marca del orgullo profesional que el programador pone en sus creaciones. Existen dos clases de documentación: externa e interna. En este artículo mencionaremos brevemente el primer tipo, y nos concentraremos principalmente en el tipo de documentación interna, conocida como comentarios dentro del código.
Contenido 1. 2. 3. 4. 5.
Documentación Externa Documentación Interna El Estilo de Programación como Documentación Listas de Chequeo para el Código Autodocumentado Claves para Comentarios Efectivos 5.1 Tipos de Comentarios 5.2 Comentar Eficientemente 5.3 El Número Óptimo de Comentarios 6. Técnicas para Comentar Código 6.1 Comentar Líneas Individuales 6.2 Los Problemas de los Comentarios de Fin de Línea 6.3 Cuando Usar Comentarios de Fin de Línea 7. Comentar Bloques de Código 8. Comentar las Declaraciones de Datos 9. Comentar las Estructuras de Control 10. Comentar Rutinas 11. Comentar Clases, Ficheros y Programas 11.1 Lineamientos Generales para la Documentación de Clases 11.2 Lineamientos Generales para la Documentación de Ficheros 11.3 La Analogía del Libro para la Documentación de Programas 12. Listas de Chequeo para Buenas Técnicas de Documentación
1. Documentación Externa La documentación en un proyecto de software consiste en información tanto dentro del código fuente como fuera de él –generalmente en forma de documentos separados. En los proyectos formales de desarrollo de software la mayoría de la documentación es de éste último tipo. En esta categoría están no sólo los más visibles para los usuarios tales como los manuales de operación y de instalación del software, sino también los documentos de diseño utilizados durante el desarrollo del software: copia de los requerimientos, copia del algoritmo empleado así como de las alternativas consideradas, diagramas de flujo, copia de los documentos que se utilizan para el diseño de las entradas y salidas visuales o impresas, copia de los estándares de desarrollo, listado más actual del código fuente, documentos relacionados con las modificaciones hechas al proyecto, así como notas importantes de diseño usadas por los desarrolladores durante el diseño y la implementación, entre otras. Por lo general estos documentos se agrupan en una carpeta especial y es empleada solamente para fines de uso interno. Puede existir un documento de diseño más detallado a nivel de código que describe decisiones de diseño a nivel de unidad de programación (una clase, una rutina o un programa), las alternativas que fueron consideradas durante la codificación y las razones por las que se seleccionaron las aproximaciones elegidas. Algunas veces toda esta información está contenida en un documento formal, pero a menudo está en una carpeta de uso personal del programador. En ambos casos, esta información de nivel tan detallado está separada del código. Pero a veces sucede que existe solamente en el código mismo.
2. Documentación Interna A diferencia de la documentación externa, la documentación interna se encuentra dentro del código mismo y es la más detallada de las dos. Puesto que es la más cercana al código, la documentación interna es la que se suele mantener más actualizada y correcta a medida que el código se modifica. La documentación interna es muy importante puesto que facilita grandemente la lectura y comprensión del código, tanto para el propio programador como para todos los que necesiten leerlo, y es especialmente útil en las fases de prueba y mantenimiento de los programas. Todos los lenguajes de programación ofrecen secuencias de caracteres que permiten la inclusión de comentarios en el código. En este artículo usaremos la simbología de C estándar y C++ (/* */ y //), para los comentarios. Si usas otro lenguaje, utiliza su simbología correspondiente.
1 de 15
07/04/2007 19:18
NeoProgramadores - Cómo Documentar Código con Efectividad
http://www.galeon.com/neoprogramadores/howdocod.htm
3. El Estilo de Programación como Documentación El principal contribuyente de la documentación a nivel de código no son los comentarios, sino el buen estilo de programación, el cual incluye una buena estructura de programa, el uso de un acercamiento directo y fácilmente comprensible, buenos nombres de variables y de rutinas, uso de constantes nombradas en lugar de valores literales, un esquema claro y la minimización de la complejidad del control de flujo y de las estructuras de datos. El código de los programas escritos con un estilo pobre de programación casi siempre es críptico. Aún cuando se le trate de explicar usando comentarios, su calidad no se ve mejorada: permanece oscuro, difícil de leer y de modificar. La única manera de clarificarlo es rescribiéndolo usando un mejor estilo de programación. De este modo el código será más legible, aún si no posee comentarios que lo expliquen. El código que es legible por sí solo se denomina código autodocumentado, y es una característica deseable para cualquier programa de software. Tal código descansa en el buen estilo de programación utilizado en su creación para sobrellevar la mayor parte de la documentación interna. En un código bien escrito, los comentarios son piezas de información realmente necesarias que complementan la legibilidad y no una carga extra que, aunque de utilidad, hace que se incremente el tamaño del código fuente.
4. Listas de Chequeo para el Código Autodocumentado Las siguientes preguntas, agrupadas por temas, son de gran ayuda para determinar si un código en particular es autoexplicativo. Todas ellas representan aspectos importantes del buen estilo de programación. Clases ¿Presenta la interfaz de la clase una abstracción consistente? ¿Tiene la clase un nombre adecuado, y este nombre describe su propósito principal? ¿La interfaz de la clase hace obvio cómo se le debería usar? ¿Es la interfaz de la clase lo suficientemente abstracta, tal que no tienes que pensar sobre cómo se implementan sus servicios? ¿Puedes tratar a la clase como una caja negra? Rutinas ¿El nombre de cada rutina describe exactamente lo que hace? ¿Desempeña cada rutina una tarea bien definida? ¿Los componentes de cada rutina que se beneficiarían de colocarse en sus propias rutinas, se han puesto en sus propias rutinas? ¿Es obvia y clara la interfaz de cada rutina? Nombres de Datos ¿Los nombres de tipos de datos son lo suficientemente descriptivos, tal que ayudan a documentar las declaraciones de datos? ¿Se han nombrado adecuadamente las variables? ¿Son las variables usadas únicamente para el propósito para el cual fueron nombradas? ¿Se le han asignado nombres más informativos a los contadores de ciclos, en lugar de i, j y k? ¿Se utilizan constantes nombradas en lugar de constantes literales? ¿La convención de nombres de identificadores empleada distingue entre los nombres de tipos de datos, los tipos enumerados, las constantes nombradas, las variables locales, las variables de clases, y las variables globales? ¿Se utilizan tipos enumerados bien nombrados en lugar de corrimientos de bits o variables booleanas? Organización de Datos ¿Se utilizan variables extras para efectos de claridad cuando es necesario? ¿Están las referencias a variables lo más cercanas a su declaración? ¿Son los tipos de datos lo suficientemente simples, tal que minimizan la complejidad? ¿Son accedidos los datos a través de rutinas de acceso abstractas (tipos de datos abstractos)? Control ¿Es claro el flujo de ejecución a través del código? ¿Están las sentencias de código relacionadas agrupadas o cercanas entre sí? ¿Se han empacado los grupos independientes de sentencias en sus propias rutinas? ¿Se ha colocado el caso más común de entre dos posibilidades en la parte if en lugar de en la parte else de una estructura condicional simple? ¿Son las estructuras de control lo suficientemente simples, tal que minimizan la complejidad? ¿Cada ciclo desempeña una y solo una función, como debería hacerlo una rutina bien diseñada? ¿Se ha minimizado el anidamiento (de ciclos y rutinas por ejemplo)?
2 de 15
07/04/2007 19:18
NeoProgramadores - Cómo Documentar Código con Efectividad
http://www.galeon.com/neoprogramadores/howdocod.htm
¿Se ha minimizado el anidamiento (de ciclos y rutinas por ejemplo)? ¿Han sido simplificadas las expresiones booleanas usando variables booleanas adicionales, funciones booleanas y tablas de decisión? Esquema ¿El esquema del programa muestra su estructura lógica? Diseño ¿Es el código directo, y evita los hackeos habilidosos? ¿Se han ocultado al máximo los detalles de la implementación? ¿Está el programa escrito en términos del dominio del problema tanto como es posible en lugar de en términos de las ciencias computacionales o de las estructuras del lenguaje de programación?
5. Claves para Comentarios Efectivos 5.1 Tipos de Comentarios 5.2 Comentar Eficientemente 5.3 El Número Óptimo de Comentarios Los comentarios erróneos al código pueden confundir a sus lectores, incluso si el código se ha escrito usando un buen estilo de programación. El código con este tipo de comentario es peor que el código sin comentarios. Por otro lado, si los comentarios son correctos pero sólo repiten verbosamente las sentencias de código, no añaden valor al código mismo. Por último, los comentarios pobres o crípticos no son de mucha ayuda y tienden a ser mal entendidos o pasados por alto debido a que obstruyen la correcta comprensión del código.
5.1 Tipos de Comentarios Repetitivos del Código: Replantean lo que el código dice en lenguaje común. Meramente dan al lector más que leer sin agregar información adicional de valor. Explicativos del Código: Son usados típicamente para explicar piezas de código complicadas, truculentas o sensibles. En tales situaciones son útiles, pero únicamente debido a que el código es confuso. Si el código es tan complicado que necesita ser explicado, casi siempre es preferible mejorar el código que añadir comentarios. Deberías hacer más claro el código mismo, y luego usa comentarios de resumen. Marcadores en el Código: Son los que se colocan a la izquierda en el código. Es una nota que el desarrollador deja para sí mismo a fin de indicar que el trabajo ahí aún no está terminado. Puede ser una instrucción sintácticamente incorrecta para que el compilador la detecte, o bien un conjunto específico de caracteres como un comentario que pueda ser localizado fácilmente sin interferir con la compilación. Resumen del Código: Es un comentario de una o dos líneas que resumen un pequeño grupo de sentencias. Son más valiosos que los comentarios repetitivos debido a que pueden leerse más rápidamente que al código. Son particularmente útiles cuando alguien distinto al autor trata de modificar el código. Descriptivos del Propósito del Código: Son los que intentan explicar la intención de una sección de código. Operan más a nivel del problema que a nivel de la solución. Por ejemplo: /* Capture la información de la factura actual */ 5.2 Comentar Eficientemente El comentar efectivamente no consume mucho tiempo. Los comentarios excesivos son tan malos como la existencia de pocos de ellos, por lo que lograr el equilibrio es importante. Puede tomar mucho tiempo escribir comentarios por dos razones comunes. La primera, el estilo de comentarios puede consumir demasiado tiempo o ser tedioso –de hecho, un dolor de cabeza. Si cabe, busca un nuevo estilo. Un estilo que requiera mucho trabajo mantener es un dolor de cabeza: Si los comentarios son difíciles de cambiar, no se cambiarán: se volverán imprecisos y llevarán a confusión, lo cual es peor que no tener comentarios del todo. La segunda razón, el comentar podría ser difícil debido a que las palabras para describir lo que el programa está haciendo no surgen fácilmente. Eso usualmente es una señal de que no se entiende bien lo que hace el programa. El tiempo que se invierte en “comentar” es en realidad tiempo invertido en comprender mejor el programa, lo cual es tiempo que necesita invertirse sin importar si lo comentas o no. A partir de aquí mencionaré tips que te ayudarán a comentar eficientemente el código de tus programas. Usa estilos que no interrumpan o desalienten la modificación Un estilo caprichoso es engorroso de mantener. Los siguientes son ejemplos de estilos de comentarios que no deben emplearse:
3 de 15
07/04/2007 19:18
NeoProgramadores - Cómo Documentar Código con Efectividad
http://www.galeon.com/neoprogramadores/howdocod.htm
comentarios que no deben emplearse: Ejemplos en C++ de Estilos de Comentarios Difíciles de Mantener // Variable Significado // -----------------// xPos. . . . . Posición de la Coordenada X (en metros) // yPos. . . . . Posición de la Coordenada Y (en metros) // Ubicado . . . Bandera que indica si ya se ubicó el punto // dado por las variables xPos y yPos // (= 0 si no está ubicado // = 1 si ya está ubicado) /************************************************ * Rutina: calcularTotalVentas * * * * Autor: J. F. Díaz * * * * Rutina para calcular el total de las ventas * * mensuales. Utiliza los registros de facturas * * almacenados en los archivos de datos. * * * ***********************************************/ En el primer caso, aunque los puntos suspensivos se ven bien, hacen el código difícil de mantener pues debe mantenerse la alineación entre la columna Variables y la columna Significado. Ello añade trabajo extra a la tarea de actualizar los comentarios sólo para que se vean bien. Los puntos suspensivos se pueden eliminar y la lista aún se ve bien. En el segundo caso, aunque el bloque de comentario tiene un buen aspecto, no es fácil de cambiar el contenido de sus líneas pues el bloque se desalinea. Debe por tanto dedicarse tiempo y esfuerzo a mantener la apariencia del bloque. En la práctica, es muy probable que en ambos casos los comentarios no se actualicen simplemente por el trabajo extra que debe hacerse para mantener el esquema del estilo de comentarios. Para el último caso, que es el más complicado, se sugiere la siguiente alternativa que se ve tan buena como la anterior pero sin los inconvenientes mencionados: Ejemplo en C++ de un Estilo de Comentario Fácil de Mantener /************************************************ Rutina: calcularTotalVentas Autor: J. F. Díaz Rutina para calcular el total de las ventas mensuales. Utiliza los registros de facturas almacenados en los archivos de datos. ***********************************************/ En los lenguajes que ofrecen más de una forma de incluir comentarios (C++ por ejemplo que utiliza // y /* ... */) se sugiere utilizar la más simple para comentarios cortos (no más de una línea de texto) y la forma más larga para comentarios extensos que incluyan más de una línea, a fin de reducir el número de caracteres necesarios para los comentarios, evitando así dificultades para su mantenimiento. Un último estilo de comentarios difícil de mantener es el siguiente: Ejemplo en C++ de un Estilo de Comentario Difícil de Mantener // Permita al usuario modificar los datos actuales // ----------------------------------------------. . . // Actualice los campos del registro // --------------------------------. . . Las líneas de guiones se utilizan para destacar los comentarios del código. Pero es claro que al modificar los comentarios, deberán ajustarse las líneas de guiones que los subrayan si la longitud del texto varía. ¿Qué debe hacerse si el comentario requiere de más de una línea? ¿Debería abreviarse el comentario para que quepa en una sola línea, subrayar cada una de ellas o dejar una sola línea de guiones para todo el comentario? Estos son los problemas que podrían surgir al intentar mantener consistente el estilo de comentarios. Una alternativa para eliminar estos problemas es sustituir las líneas de guiones por líneas en blanco -usando quizá una macro del editor de texto. Otra sería adoptar la convención de mantener todas las líneas de guiones del mismo tamaño, y subrayar una sola vez los comentarios cuando consten de más de una línea, si aún se desea destacarlos del código. Integra comentarios en tu estilo de programación El ir comentando el código a medida que se escribe tiene la ventaja de que se va introduciendo mientras más frescos se tienen los detalles de programación. Comentar al final, por el contrario, consume más tiempo puesto que se deben recordar los detalles y las sutiles suposiciones de la programación, o leer de nuevo el código para comprenderlo, antes de escribir los comentarios, haciendo que estos sean menos precisos. Muchos argumentan que la programación requiere mucha concentración, la cual no debe interrumpirse ni siquiera para escribir comentarios. Para rebatir este argumento podemos decir que si el código requiere mucha concentración es una clara señal de que es complejo, pero una alternativa sería utilizar el algoritmo como punto de partida para la codificación e
4 de 15
07/04/2007 19:18
NeoProgramadores - Cómo Documentar Código con Efectividad
http://www.galeon.com/neoprogramadores/howdocod.htm
pero una alternativa sería utilizar el algoritmo como punto de partida para la codificación e ir convirtiendo las frases en comentarios a medida que codificamos. Si tu diseño es difícil de codificar, simplifícalo antes de empezar a preocuparte del código o los comentarios. Si usas el algoritmo o el seudocódigo para clarificar tus ideas, la codificación será directa y los comentarios automáticos. El desempeño no es una buena razón para no comentar Cierto. Los comentarios incrementan el tamaño de los archivos de código fuente. Aunque los compiladores modernos son capaces de obviar los comentarios al momento de traducirlos a código objeto y a programas ejecutables, en algunos ambientes como la Internet donde debe enviarse una copia del programa para ser interpretado en máquinas clientes (código ASP y applets de Java y JavaScript, por ejemplo) el tiempo invertido en enviar la información extra que representan los comentarios a través de la red puede ser prohibitivo pues penaliza el desempeño de las aplicaciones, aún si éstas se ejecutan en hardware remoto eficiente. Sin embargo, eso no quiere decir que no se deba comentar el código. Los tips del resto de este artículo enseñan a comentar eficientemente el código, de tal manera que no sobrecarguen excesivamente el archivo fuente. Aún así, una solución práctica para este problema es tener dos versiones del código: una comentada y otra en producción. El truco consiste en escribir un programa que filtre los comentarios de los archivos fuente (que busque y deseche del código todo el texto que se halla protegido por las secuencias sintácticas que el lenguaje usa para los comentarios) antes de pasar al proceso de compilación o implantación en los servidores de las aplicaciones remotas. Una especie de stripper. 5.3 El Número Óptimo de Comentarios La regla es que no hay reglas… o no la debería haber. Aclaro: Establecer en un proyecto de programación una norma estándar de un comentario por cada cierto número de sentencias de código es peligroso. Los programadores estarán más preocupados por cumplir la norma que por escribir código claro y eficiente. El utilizar el algoritmo o el seudocódigo como punto de partida para la codificación tendrá como efecto colateral comentarios muy precisos. En lugar de enfocarnos en el número de comentarios, enfoquémonos en que cada uno de ellos sea eficiente. Si el código describe porqué fue escrito el código y satisface todos los criterios de este documento, tendrás suficientes comentarios.
6. Técnicas para Comentar Código 6.1 Comentar Líneas Individuales 6.2 Los Problemas de los Comentarios de Fin de Línea 6.3 Cuando Usar Comentarios de Fin de Línea Los comentarios dependen de lo que se quiera comentar: líneas individuales, un bloque de sentencias de código, una rutina, un archivo o un programa completo.
6.1 Comentar Líneas Individuales Si el código es bueno, es raro que requiera comentarios. Dos posibles razones por las cuales una línea individual de código podría necesitar un comentario son: 1. La línea de código es tan compleja que necesita una explicación 2. La línea de código tenía un error y quieres guardar un registro del error 6.2 Los Problemas de los Comentarios de Fin de Línea Los comentarios de fin de línea son útiles en ciertas circunstancias, pero poseen problemas. Deben ser alineados a la derecha del código de tal forma que no interfieran con la estructura visual del código, o de lo contrario obstruirán su lectura. Este trabajo extra los hace difíciles de formatear. La tediosa tarea de presionar la barra espaciadora o la tecla TAB cansa y consume tiempo, el cual debería ser invertido en el código. Los comentarios de fin de línea son también difíciles de mantener. Si el código de una línea que contiene uno de estos comentarios crece, obliga a realinear el resto de comentarios de fin de línea para mantener el formato. Como mencionamos antes, los estilos de comentarios que son difíciles de mantener provocan que no se actualicen los comentarios o no se preserve dicho estilo. Por último, los comentarios de fin de línea tienden a ser crípticos por el poco espacio que se tiene a la derecha del código, lo que obliga a que el comentario sea breve. Esto obliga a los programadores a escribir líneas de código cortas en lugar de escribir código más claro, lo cual dificulta su lectura. Evita comentar cada línea de código Además de los problemas prácticos, los comentarios de fin de línea poseen problemas conceptuales. Es difícil escribir un comentario realmente significativo para cada línea de código sin caer en la repetición del código mismo. El cansancio resultante más bien daña la moral del programador y al proyecto de programación por el tiempo que se pierde en tal actividad. Se deben comentar solamente las líneas de código que lo ameriten.
5 de 15
07/04/2007 19:18
NeoProgramadores - Cómo Documentar Código con Efectividad
http://www.galeon.com/neoprogramadores/howdocod.htm
actividad. Se deben comentar solamente las líneas de código que lo ameriten. Evita comentarios de fin de línea para múltiples líneas de código El formato de los comentarios de fin de línea no es útil para múltiples líneas puesto que no muestra a cuáles líneas se le aplica. El siguiente ejemplo ejemplifica esto: Ejemplo en Pascal de un Comentario Confuso de Fin de Línea para Varias Líneas de Código FOR i := 1 TO cantAgentes {Calcule las comisiones de ventas} BEGIN sumarVentas(i, totalVentas); Comisiones[i] := totalVentas * 0.05; END Aunque el comentario es correcto, su ubicación no lo es, por cuanto obliga a leer tanto el comentario como el código para saber si el primero se aplica a la línea en la que está o a todo el ciclo. En estos casos lo mejor es colocarlo en la línea anterior al FOR. Evita usar comentarios de fin de línea para notas de mantenimiento Registrar en comentarios de fin de línea modificaciones al código inicial (tal como el tipo de error que generaba o los síntomas que llevaron a descubrirlo) deberían guardarse, si es que son importantes, en la documentación externa, en una hoja de papel. Los comentarios deberían explicar el código actual y no como fallaba en el pasado. Aunque esto contradice una de las razones por la cual una línea individual de código podría necesitar un comentario, se acepta únicamente en el caso de que el error sea producto de una falla del compilador o del sistema (el hardware o su software operativo). De este modo, el comentario de fin de línea será una advertencia para que quienes modifiquen posteriormente el programa no corrijan la línea de código tal como, en teoría, debería funcionar. 6.3 Cuando Usar Comentarios de Fin de Línea Aunque en general no deben emplearse comentarios de fin de línea, existen 2 excepciones en las cuales son útiles: Usa comentarios de fin de línea para las declaraciones de datos Puesto que en las declaraciones se tiene suficiente espacio por tratarse de líneas cortas, los comentarios de fin de línea son útiles aquí, pues se pueden escribir comentarios significativos junto a cada declaración. Este es un ejemplo: Ejemplo en C de Comentarios de Fin de Línea para Declaraciones de Datos int xPos; /* Coordenada X del punto */ int yPos; /* Coordenada Y del punto */ int Puntos[10][2] /* Arreglo de coordenadas del gráfico */ Usa comentarios de fin de línea para marcar el fin de los bloques de código Un comentario de fin de línea es útil para indicar el fin de un bloque de código largo, o para señalar dónde termina un bloque interno cuando se está utilizando el anidamiento de estructuras (ciclos anidados, por ejemplo.)
7. Comentar Bloques de Código La mejor manera de comentar programas es escribir comentarios de una o dos líneas que describan bloques de código. Por ejemplo: Ejemplo en C de un Buen Comentario para un Bloque de Código /* Intercambie las raíces */ temp = raiz_1; raiz_1 = raiz_2; raiz_2 = temp; El comentario del ejemplo no repite el código, sino que describe su intención. Tales comentarios son relativamente fáciles de mantener. Aún si el código contiene un error, el comentario no se modificará. Escribe comentarios que describan la intención del código En lugar de repetir el código, escribe comentarios que describan el propósito del código. El siguiente es un ejemplo que repite el código: Ejemplo en C de un Comentario No Efectivo /* Revise cada carácter en cadenaDeEntrada hasta que se encuentre un signo de dólar o todos los caracteres hayan sido revisados */ Terminado = False; maxLen = strlen(cadenaDeEntrada) – 1; i = 0; while (!Terminado && (i < maxLen)) { if (cadenaDeEntrada[i] == ‘$’) {
6 de 15
07/04/2007 19:18
NeoProgramadores - Cómo Documentar Código con Efectividad
http://www.galeon.com/neoprogramadores/howdocod.htm
{ Terminado = True; } else { i++; } } Lo que dice el comentario lo puedes intuir observando el código, por lo que el comentario sale sobrando. El problema es que el comentario repite el código y no dice lo que se supone que hará. Sería mejor si fuera: /* Encuentre el carácter ‘$’ en la variable cadenaDeEntrada */ Este comentario es mejor porque indica la meta del ciclo, pero no es perfecto puesto que no explica por qué se busca el carácter ‘$’. Si lo rescribimos así: /* Encuentre el carácter de terminación de comando ($) */ El comentario es mejor y verdaderamente útil porque contiene información que el código no dice: que el carácter ‘$’ finaliza un comando, lo cual no podrías deducir del código. El código también puede ser autodescriptivo, asignando a las variables y rutinas nombres que describan su propósito. Si convertimos el código anterior en una rutina y le asignamos el nombre HallarCaracterDeFinDeComando el comentario hasta sale sobrando. El único problema con esto es que si el código evoluciona (se modifica para llevar a cabo otras funcionalidades), el nombre de la rutina habrá que cambiarlo para que describa con exactitud lo que ella llevaría a cabo. Enfoca tus esfuerzos de documentación en el código mismo El código mismo debería ser la mejor documentación de tus programas. En el ejemplo anterior, el carácter ‘$’ debería reemplazarse por una constante y las variables deberían tener mejores nombres para ayudar a la comprensión del código. El ejemplo anterior reescrito con buenos comentarios y un mejor estilo de programación es: Ejemplo en C de un Buen Comentario y un Buen Estilo de Programación /* Encuentre el carácter de terminación de comando ($) */ finDeComandoEncontrado = False; longitudDeLaCadena = strlen(cadenaDeEntrada) – 1; indiceDeLaCadena = 0; while (!finDeComandoEncontrado && (indiceDeLaCadena < longitudDeLaCadena)) { if (cadenaDeEntrada [indiceDeLaCadena] == FIN_DE_COMANDO) { finDeComandoEncontrado = True; } else { indiceDeLaCadena = indiceDeLaCadena + 1; } } Aunque ahora el comentario parece redundante por lo autoexplicativo que es el código, debería mantenerse como encabezado del bloque a fin de reforzar la documentación. Enfoca el comentario del bloque en el por qué en lugar del cómo Los comentarios que explican cómo se hace algo están a un nivel de programación, algo técnicos, en lugar de estar a nivel del problema. Veamos el siguiente ejemplo: Ejemplo en C de un Comentario que se Enfoca en el Cómo /* Si la bandera de la cuenta es cero */ if (banderaDeCuenta == 0) . . . Este comentario sólo repite el código y no le añade valor adicional. Veamos este: Ejemplo en C de un Comentario que se Enfoca en el Por Qué /* Si se establece una nueva cuenta */ if (banderaDeCuenta == 0) . . . Este comentario es mejor porque dice algo que no puede intuirse del código mismo. Usa comentarios para preparar al lector sobre lo que sigue Los buenos comentarios le dicen a quien lee el código qué esperar. De este modo, el lector buscaría únicamente los comentarios y obtendría una idea más rápida de lo que el código hace, o encontraría con mayor velocidad una pieza particular de código. Haz que cada comentario cuente El exceso de comentarios oscurece el código que se intenta clarificar. En lugar de escribir demasiados comentarios esfuérzate en hacer que el código sea más legible y que cada comentario valga cada byte que ocupa.
7 de 15
07/04/2007 19:18
NeoProgramadores - Cómo Documentar Código con Efectividad
http://www.galeon.com/neoprogramadores/howdocod.htm
comentario valga cada byte que ocupa. Evita las abreviaturas Los comentarios no deberían ser ambiguos y fácilmente legibles sin el trabajo de adivinar abreviaturas. La única excepción es cuando estás usando comentarios de fin de línea para documentar declaraciones de datos o como señaladores de fin de bloques de código. Aunque te veas tentado a usar abreviaturas, recuerda siempre que ellas van en detrimento de la claridad que se supone estás deseando darle a tu código mediante los comentarios. Diferencia entre comentarios principales y secundarios En algunos casos desearás diferenciar niveles de comentarios, indicando que un comentario es parte de otro más amplio. Puedes hacerlo de varias formas: Subrayando con una línea de guiones (u otro caracter) el comentario principal y dejando sin subrayar los comentarios secundarios Colocando puntos suspensivos al inicio de los comentarios secundarios para denotar continuidad de un comentario principal previo Indentando los comentarios secundarios para denotar subordinación a un comentario principal precedente Aunque simple y efectiva, la primera alternativa peca por exceso de comentarios (necesitarás un comentario por cada línea de guiones) y conduce a confusión con los comentaris independientes, los cuales necesitarían su propia línea de guiones para no parecer subordinados al comentario principal precedente, lo cual incrementa el número de comentarios aún más. La segunda y tercera alternativa son mejores, pero se aconseja la tercera por requerir menos caracteres y por ser su estilo de documentación (o formato) más fácil de mantener --es mejor y más práctico una pulsación de tabulador que tres pulsaciones para crear los puntos suspensivos. Documenta las sorpresas Si hay lago que no es obvio a partir del código mismo, documéntalo con un comentario. Cada truco técnico que uses para mejorar el desempeño, por ejemplo, debería ser comentado. Debe señalarse en él por qué no se utilizó un método más directo y mencionar la ganancia en desempeño alcanzada con el truco. Por ejemplo: Ejemplo en C++ de la Documentación de Una Sorpresa for (elemento = 0; elemento < contadorDeElemento; elemento++) { // Use el desplazamiento de un bit a la derecha // para dividir por dos. La sustitución de la división // acorta el tiempo del ciclo en un 75% ListaDeItems[elemento] = ListaDeItems[elemento] >> 1 } La selección del desplazamiento a la derecha en este ejemplo es intencional. Entre los programadores experimentado, es de dominio común que para los enteros, el desplazamiento a la derecha es funcionalmente equivalente a dividir entre dos. Si es de dominio común ¿por qué documentarlo? Porque el propósito de la operación no es ejecutar un desplazamiento a la derecha, sino una división ente dos. El hecho de que el código no use la técnica usual para su propósito es significativo. Sin embargo, la mayoría de los compiladores optimizan la división entera entre dos con el desplazamiento a la derecha, por lo cual el truco solo reduce la claridad del código y es innecesario. En este caso particular, el compilador evidentemente no optimiza la división entre dos, y el tiempo ahorrado será significativo. Con la documentación, un programador que esté leyendo el código vería la motivación de no usar la técnica obvia. Sin los comentarios, el mismo programador estaría inclinado a quejarse de que el código es innecesariamente mañoso sin ninguna ganancia significativa en desempeño. Tal queja es usualmente justificada, por lo cual es importante documentar las excepciones. Comenta cualquier truco que evite un error o una funcionalidad no documentada en un lenguaje o entorno Si es un error, probablemente no esté documentado. Aún si está documentado en alguna parte, no daña el documentarlo de nuevo en tu código. Si es una funcionalidad indocumentada, debería estarlo en tu código. Supón que encuentras que la rutina de biblioteca WriteData(data, numItems, blockSize) funciona apropiadamente excepto cuando blockSize es igual a 500. Ella funciona bien con 499, 501 y cualquier otro número que has probado, pero encuentras que el error aparece solamente cuando blockSize es igual a 500. En el código que usa WriteData, documenta por qué haces un caso especial cuando blockSize es igual a 500. Este es un ejemplo de cómo podría verse: Ejemplo en C++ de Documentación de un Truco para Evitar un Error blockSize = optimalBlockSize (numItems, sizePerItem); /* El siguiente WriteData() que es igual a 500. para efectos de
código es necesario para evita un error en aparece solamente cuando el tercer parámetro '500' se ha reemplazado por una constante claridad */
if (blockSize == WRITEDATA_BROKENSIZE)
8 de 15
07/04/2007 19:18
NeoProgramadores - Cómo Documentar Código con Efectividad
http://www.galeon.com/neoprogramadores/howdocod.htm
if (blockSize == WRITEDATA_BROKENSIZE) { blockSize = WRITEDATA_WORKAROUND_SIZE; } WriteData(data, numItems, blockSize); Justifica las violaciones al buen estilo de programación Si has violado alguna norma del buen estilo de programación, explica el por qué. Ello prevendrá a un programador bien intencionado de cambiar el código para darle un mejor estilo, con la posibilidad de introducir errores. La explicación hará claro que sabías lo que hacías y que no estabas tonteando. ¡Date el crédito que mereces! No comentes código truculento No uses los comentarios para documentar (y proteger así) el mal código, aún si es la parte más importante de tu programa. El comentar el código truculento es lo que no deberías hacer puesto que los comentarios no rescatarán el código difícil. En casos como estos, lo que debes hacer es seguir la regla de Kernighan y Pike, “No documentes el mal código -rescríbelo.” Generalmente el código truculento es profusamente documentado por su complejidad inherente. Pero se sabe que el código más documentado es el que suele tener la mayor cantidad de errores y a consumir el mayor esfuerzo de desarrollo y mantenimiento por su grado de dificultad. El código truculento es un mal código por que resulta difícil de comprender y darle mantenimiento. Si una pieza de código te parece truculenta, de seguro lo será lo es y será difícil para cualquier otro programador. Si tu código te parece truculento, debes hallar una forma de rescribirlo que no lo sea, así que búscala. Haz tu código tan bueno que no necesite comentarios, y luego coméntalo para hacerlo aún mejor. Este consejo se aplica en primera instancia al código que escribes. Si estás dándole mantenimiento a un programa y no tienes la capacidad de rescribir el mal código, comentar las partes truculentas es una buena práctica de programación.
8. Comentar las Declaraciones de Datos Los comentarios para las declaraciones de variables describen aspectos de la variable cuyo nombre mismo no puede describir. Es importante documentar los datos cuidadosamente puesto que esa documentación es incluso más importante que las notas sobre los procesos en los cuales se utilizan los datos. Los siguientes tips son guías para documentar datos: Comenta las unidades de datos numéricos Cada variable o campo que vaya a contener cantidades numéricas que representen unidades de medida debería tener documentada la unidad de medida que representa. Así, si una variable representará longitud debería documentarse si representará centímetros, pulgadas, metros, kilómetros, etc. Si representará peso, entonces su comentario debe especificar si serán gramos, onzas, libras, kilos, toneladas, etc. Si son coordenadas, si indicarán latitud, longitud o altitud, y si está en grados o radianes; si representarán una coordenada X, Y, X con su origen en el centro de la tierra, y cosas así. No asumas que las unidades son obvias pues para un nuevo programador u otro que esté trabajando en otra parte del programa/sistema, no lo serán. Mucho menos si el programa ha sido sustancialmente modificado. Ejemplo en C de Documentación de Unidades de Datos Numéricos int XCursor; /* Pos. horizontal del cursor; desde 1 hasta MaxCols */ int YCursor; /* Pos. vertical del cursor; desde 1 hasta MaxFilas */ Comenta el rango de los valores numéricos permisibles Si una variable debe estar dentro de un rango de valores, documenta ese rango en la declaración de la variable. Si tu lenguaje de programación dispone de tipos de datos que son subconjuntos de otros --Pascal por ejemplo, que ofrece los tipos BYTE y LONGINT, y C que permite tipos de datos enteros adicionales al int tan solo antecediendo la palabra clave int con otras que actúan a modo de modificadores, como short long. Si tu lenguaje no ofrece de subtipos de datos (lo cual es raro hoy en día) usa los comentarios para documentar el rango de valores esperados. Por ejemplo, si una variable representará calificaciones, indica en su comentario que se espera que sus valores estén entre 0 y 100 inclusive. Además de esto, deberás incluir código que valide la entrada de datos para esa variable a fin de que minimices las posibilidades de error en la ejecución. Ejemplo en C de Documentación de Rango de Valores Numéricos Permisibles long int longitudAntena; /* longitud de la antena en metros; debe ser >=2 */ Comenta significados codificados Si tu lenguaje soporta tipos enumerados -como C++ y Visual Basic por ejemplo- úsalos para expresar significados codificados. Si no lo hace, usa comentarios para indicar lo que
9 de 15
07/04/2007 19:18
NeoProgramadores - Cómo Documentar Código con Efectividad
http://www.galeon.com/neoprogramadores/howdocod.htm
para expresar significados codificados. Si no lo hace, usa comentarios para indicar lo que cada valor representa -y usa una constante nombrada en lugar de una literal para cada uno de los valores. Si una variable representa tipos de corrientes eléctricas, comenta el hecho de que 1 representa corriente alterna, 2 representa corriente directa y que 3 representa corriente indefinida. Ejemplo en C de Documentación de Significados Codificados int atributoDelCaracter; /* 0=Plano; 1=Cursiva; 2=Negrita; 3=Negrita Cursiva */ Comenta las limitaciones de los datos de entrada Los datos de entrada pueden venir de distintas fuentes: de un archivo, del teclado, como un parámetro desde o hacia una rutina, etc. Los tips anteriores se aplican tanto a los parámetros de entrada para las rutinas como a cualquier otro tipo de datos. En cualquier caso, asegúrate de que tanto los datos esperados como los no esperados estén documentados. Los comentarios son una forma de documentar que una rutina nunca se supone que reciba ciertos datos. La programación defensiva por medio de aserciones (empleando ciclos y sentencias if, posiblemente junto con directivas del procesador) es otra forma de documentar los rangos válidos. De este modo el código se vuelve más autoverificable. Actualiza los comentarios relacionados a las variables Si tienes comentarios específicos para una variable, asegúrate que se actualicen cada vez que la variable es actualizada, especialmente en las modificaciones al código y cuando la variable, por alguna razón, cambie de nombre durante la programación. De este modo las modificaciones serán consistentes. Documenta los datos globales Si usas una variable o una estructua de datos global, documéntala bien en el punto donde es declarada. Los comentarios deberían indicar el propósito de ese elemento y por qué necesita ser global. En cada punto donde sea utilizada, aclara que esa variable o estructura de datos es global. El usar una convención de nombres (tales como una g) ayuda a distinguir las variables y estructuras de datos globales de las demás y puede hacer menos necesaria la documentación. Pero aún así, conviene mantenerlos.
9. Comentar las Estructuras de Control Las estructuras de control son principalmente las sentencias condicionales o de selección (if y case) y los ciclos. Los siguientes tips son útiles para la documentación de estos tipos de instrucciones: Coloca un comentario antes de cada estructura de control Las estructura de control a menudo necesitan explicación, y el mejor lugar para documentarlas es justo el espacio antes de ellas. En el caso de una sentencia de selección, puedes incluir la razón para la decisión y un resumen del resultado. Si es un ciclo, puedes indicar su propósito y aspectos importantes de su ejecución. Documenta la línea de finalización de cada estructura de control Un comentario al final del bloque de sentencias de una estructura de control ayuda a resaltar la construcción lógica del programa. Este tipo de documentación es particulamente útil en ciclos largos o en el anidamiento de estructuras de control del mismo tipo pues ayuda a clarificar el anidamiento. Ejemplo en C de Uso de Comentarios para Clarificar Anidamiento for (indiceArray=0; indiceArray < contadorArray; indiceArray++) { while (indiceRegistro < conteoRegistros) { if (BuscarRegistro(indiceRegistro)) { . . . } /* if */ } /* while */ } /* for */ Este tipo de comentarios complementa la pista visual de la estructura lógica que da la indentación del código. Aunque esta técnica no es tan necesaria en estructuras de control cortas que no están anidadas, su utilización permite mayor uniformidad y mejora el estilo de programación. Nota: Las estructuras de control demasiado extensas deberían reescribirse a fin de simplificarlas. De lo contrario, la técnica de documentar la línea de finalización de cada estructura de control se utilizaría para apañar código mal diseñado. Los comentarios de fin de estructura de control, en estos casos, deben verse como advertencias y recordatorios para refactorizar el código.
10. Comentar Rutinas Los comentarios a nivel de rutina (subprogramas y funciones, por ejemplo) suelen ser objeto de los peores consejos en los libros de texto y en los cursos de programación, lo que provoca gran confusión entre los principiantes. En muchos de estos libros y cursos se
10 de 15
07/04/2007 19:18
NeoProgramadores - Cómo Documentar Código con Efectividad
http://www.galeon.com/neoprogramadores/howdocod.htm
provoca gran confusión entre los principiantes. En muchos de estos libros y cursos se recomienda incluir una cantidad excesiva de información al inicio de cada rutina, sin tomar en cuenta su tamaño o complejidad, lo que redunda en mucho trabajo extra incluso para rutinas pequeñas y triviales. Las consecuencias directas de esta práctica son la falta de precisión en los comentarios y su no actualización durante la fase de mantenimiento. Otro problema con los encabezados de rutina voluminosos es que desalientan la buena refactorización del código: la sobrecarga que representa crear los encabezados por cada nueva rutina que se necesite para simplificar el código es tan grande que los programadores prefieren no refactorizar o crear la menor cantidad de rutinas. Las convenciones de codificación deberían alentar las buenas prácticas de programación; las convenciones demasiado complicadas como los encabezados de rutina pesados hacen lo opuesto. Los siguientes tips pueden ayudarte para documentar rutinas: Mantén los comentarios cercanos al código que describen Las rutinas no deberían tener encabezados voluminosos debido a que alejan los comentarios que describen la intención de la rutina -los cuales se suelen colocar como prólogo justo antes de ella- del código mismo que documentan. Durante el mantenimiento, los comentarios que están lejos del código tienden a no ser actualizados. A partir de ahí, los comentarios y el código empiezan a contradecirse hasta el punto en que los comentarios dejan de ser útiles. Por tal razón, los comentarios deben colocarse tan cerca del código que describen como sea posible. Así, tendrán más probabilidad de ser actualizados durante el mantenimiento y continuarán siendo útiles. Una buena idea para evitar encabezados de rutinas volumninosos es crear una "plantilla" que incluya las piezas de información que se sugieren en los tips siguientes. Puesto que no estás obligado a incluirlas todas en cada caso, completa las partes que interesen y elimina el resto. De este modo mantendrás los encabezados de rutinas útiles y no demasiado cargados. Describe cada rutina con una o dos oraciones en la línea anterior a ella Un comentario descriptivo breve permitirá conocer rápidamente el propósito de la rutina. Debes ser capaz de prologar cada rutina en dos líneas como máximo. Si tienes dificultades en crear una descripción corta para la rutina es una clara señal de que el diseño de tu programa no es tan bueno como debería. Regresa a la mesa de diseño e inténtalo de nuevo. Las rutinas triviales y cortas pueden quedar exentas de contar con un prólogo breve, pero debes juzgarlo por ti mismo de acuerdo a su importancia y objetivo. Documenta los parámetros de entrada y salida La forma más práctica de documentar variables de entrada y salida de una rutina es colocar esos comentarios justo bajo la línea de encabezado de la rutina misma. Ejemplo en C de Documentación de Variables de Entrada y Salida Buena Práctica de Programación void InsertarEnOrden(int datoAInsertar, int *ArregloDeDatos[]) /* datoAInsertar: Número a ingresar en la lista ordenada ArregloDeDatos: Array de enteros que contiene la lista de datos ordenados */ { . . . } /* InsertarEnOrden */ Esta práctica es una buena excepción a la regla de no usar comentarios de fin de línea. Los comentarios de fin de línea, como se mencionó párrafos arriba, son muy útiles para documentar declaraciones de variables. Aún cuando los nombres de los parámetros sean adecuadamente seleccionados y aparentemente hagan ver a los comentarios como redundantes, estos pueden complementar la información necesaria para comprender su propósito. Distingue a los parámetros de entrada de los de salida Es útil saber cuáles datos se utilizan como materia prima para la rutina y cuáles para comunicar los resultados. Algunos lenguajes como Pascal permiten diferenciar los parámetros de salida porque estos van precedidos de la palabra clave VAR. Ada y Visual Basic también tienen sus respectivas keywords para ello, pero otros como C y Java (este último por herencia del primero) no caracterizan a sus parámetros, y se debe conocer bien el lenguaje para poder distinguir los parámetros de entrada de los de salida. Si tu lenguaje no te permite tal diferenciación, usa comentarios. El ejemplo anterior, modificado, queda así: Ejemplo en C de Diferenciación Entre Parámetros de y de Salida void InsertarEnOrden(int datoAInsertar, int *ArregloDeDatos[]) /* datoAInsertar: Entrada - Número a ingresar en la lista ordenada ArregloDeDatos: Salida - Array de enteros que contiene la lista de datos ordenados */ {
11 de 15
07/04/2007 19:18
NeoProgramadores - Cómo Documentar Código con Efectividad
http://www.galeon.com/neoprogramadores/howdocod.htm
{ . . . } /* InsertarEnOrden */ En particular, las declaraciones de rutinas en C y C++ son un poco difíciles de comprender por cuanto usan el asterisco (*) para indicar que el argumento es de salida. El asterisco permite manejar fácilmente los datos almacenados en memoria por medio de punteros. La dificultad de comprender las rutinas en estos lenguajes se incrementa por el hecho de que en muchas ocasiones se abusa de esta característica. (C estándar, en especial, usa el asterisco para obviar la limitante que tienen sus rutinas de poder devolver solamente un valor al punto de llamada.) La práctica de distinguir los parámetros de entrada de los de salida es un servicio muy útil para cualquiera que lea la rutina, en especial si no está familiarizado con ella. Documenta las suposiciones de interfaz La documentación de suposiciones de interfaz puede verse como algo derivado del tip anterior. Si haces suposiciones sobre el estado de los argumentos que recibes --valores legales e ilegales, estructuras que deban estar ordenadas, variables y miembros de estructuras que contienen sólo datos válidos, etc.-- documéntalas en el prólogo de la rutina o en la declaración del parámetro. Este tipo de documentación debería incluirse prácticamente en todas las rutinas. Si estás haciendo algún tipo de suposición, escríbela antes de que la olvides y luego inclúyela dentro de los comentarios de la rutina. Asegúrate también de documentar las variables y estructuras de datos globales que recibas o utilices a lo interno de tus rutinas, puesto que ellas son difíciles de diferenciar del resto de parámetros. Puesto que cualquier cambio en los valores que ellas almacenan afecta directamente a todo el programa, se debe poner especial énfasis en su documentación. Comenta las limitaciones de la rutina Si la rutina devuelve un resultado numérico, indica su precisión. Si los cálculos son indefinidos bajo algunas condiciones, menciónalo. Si programaste la rutina para exhibir un determinado comportamiento o funcionar con valores por defecto cuando hay algún problema, documenta ese comportamiento. Si la rutina funciona sólo para estructuras de datos de cierto tamaño, indícalo. Si sabes de modificaciones que harán que la rutina deje de funcionar, documéntalas también. Dentro de los comentarios de la rutina debe incluirse cualquier limitante que ella tenga. Esto será de gran ayuda para quienes trabajen en un futuro con ella. Documenta los efectos globales de las modificaciones que realiza la rutina Si dentro de la rutina se modifica una variable o estructura de datos global, debes describir de forma explícita esta modificación. Sabemos que la modificación de variables y estructuras de datos globales es al menos el doble de peligroso que el solo hecho de poder accesarlas, de tal forma que las modificaciones deberían ser realizadas con sumo cuidado. Parte de ese cuidado implica documentar adecuadamente los cambios que sobre estas localidades se hacen. Si la documentación de las variables y estructuras de datos globales se vuelve demasiado problemática, lo mejor es rescribir el código para reducir o evitar el uso de tales elementos. Documenta la fuente de los algoritmos que utilizas Si has empleado un algoritmo de un libro o una revista, documenta el tomo y el número de página de donde lo tomaste. Si es de un sitio web, su dirección URL exacta. Si el algoritmo es un trabajo personal, indica al lector dónde puede encontrar las notas respectivas. En particular, referencia los algoritmos o ideas sobre las que te basaste. Todo esto sirve para fundamentar mejor tu trabajo.
11. Comentar Clases, Ficheros y Programas 11.1 Lineamientos Generales para la Documentación de Clases 11.2 Lineamientos Generales para la Documentación de Ficheros 11.3 La Analogía del Libro para la Documentación de Programas Las clases, ficheros y programas se caracerizan por el hecho de que contienen múltiples rutinas. Un fichero o una clase debería contener un conjunto de rutinas relacionadas. Un programa contiene todas las rutinas en sí mismo. El trabajo de documentación en cada caso es con el fin de proveer una visión significativa y de alto nivel de lo que contiene el fichero, la clase o el programa. En cada caso los aspectos son similares, por lo que los tips que se mencionen en esta sección se aplican a cualquiera de estos tres elementos.
11.1 Lineamientos Generales para la Documentación de Clases Para cada clase conviene usar un comentario de bloque que describa los atributos generales de la clase. Describe el diseño de la clase Los comentarios generales que brindan información que difícilmente puede extraerse del código son especialmente útiles. Describe la filosofía del diseño de la clase, aproximaciones
12 de 15
07/04/2007 19:18
NeoProgramadores - Cómo Documentar Código con Efectividad
http://www.galeon.com/neoprogramadores/howdocod.htm
código son especialmente útiles. Describe la filosofía del diseño de la clase, aproximaciones de diseño generales, alternativas de diseño que se consideraron y que se descartaron, etc. Describe las limitaciones, suposiciones de uso y cosas así Al igual que con las rutinas, asegúrate de describir las limitaciones impuestas por el diseño de la clase. Describe así mismo las suposiciones acerca de los datos de entrada y salida, responsabilidades de manejo de errores, efectos globales, fuentes de los algoritmos de sus métodos, etc. Comenta la interfaz de la clase Si otro programador no es capaz de comprender cómo usar la clase sin ver cómo ésta se implementa, es decir, sin ver el código, entonces la encapsulación de la clase está en serio riesgo. La interfaz de la clase debería contener toda la información necesaria para usar la clase. Como mínimo se requiere documentar cada parámetro y cada valor de retorno, y esto debería hacerse con cada una de las rutinas expuestas de cada clase. No documentes detalles de implementación en la interfaz de la clase Una regla básica de encapsulación es que se debe exponer solamente la información necesaria: si existe alguna duda sobre algún tipo de información necesita verse expuesta, el valor por defecto es mantenerla oculta. En consecuencia, los archivos de interfaz de la clase deberían contener la información necesaria para usar la clase, pero no información necesaria para la implementación o mantenimiento del funcionamiento interno de la clase. 11.2 Lineamientos Generales para la Documentación de Ficheros Para cada fichero, se debe usar un comentario de bloque que describa el contenido del fichero. Los siguientes tips ayudarán en la estructuración de esta documentación. Describe el propósito y contenido de cada archivo El comentario del encabezado del fichero debería describir las clases o rutinas contenidas en el fichero. Si todas las rutinas para un programa están en un único fichero, el propósito de este fichero es bastante obvio --es el que contiene el programa completo. Si el propósito del fichero es contener una clase específica, su propósito también es obvio --es el que contiene la clase con ese nombre. En caso de que el fichero contenga más de una clase, se debe explicar el por qué se combinan en un único fichero. Si la división de un programa en múltiples ficheros se hace por razones distintas a las de la modularización, conviene incluir una buena descripción de estas razones en el fichero principal (generalmente en el del programa principal). Esta descripción será extremadamente útil para quienes tengan que modificar el programa. En particular, si se referencia una rutina o clase de otro fichero, se debe documentar el nombre del fichero en que reside esa rutina o clase. Coloca tu nombre, e-mail, y número de teléfono en el comentario de bloque La autoría y responsabilidad primaria de áreas de código específicas se vuelve importante en proyectos grandes. Los pequeños proyectos (con menos de 10 personas) pueden usar el método de desarrollo colaborativo en el cual todos los miembros del equipo conocen las distintas áreas de código y son igualmente responsables de ellas. En los proyectos grandes esta técnica es impráctica, por lo que se requiere especialización. Es este caso, la información de autoría es importante. Da a los demás programadores que trabajan en el código pistas sobre el estilo de programación del autor del código, así como información de contacto en caso de necesitar ayuda. Este tipo de información debería incluirse tanto en las rutinas, clases y programas. Incluye el copyright en el comentario de bloque Si necesitas incluir el copyright de tu empresa o el tuyo propio, el lugar apropiado es la primera línea del prólogo del fichero. Un ejemplo es el siguiente: Ejemplo en C de Línea de Copyright /* (c) Copyright 2000-2005 J. F. Díaz. Todos los derechos reservados. */ ... En lugar de tu nombre, generalmente se coloca el nombre de la empresa propietaria del código. Da al fichero un nombre relacionado con su contenido Esto hará autodocumentivo al nombre de fichero. En el caso de que el fichero contenga una clase de C++ llamada Cuenta, el fichero debería llamarse Cuenta.cpp. 11.3 La Analogía del Libro para la Documentación de Programas Las técnicas descritas en las secciones previas por sí solas son débiles, pero cuando esas técnicas se combinan, evidencian una gran efectividad para el proceso de la programación, más fuerte que si se usaran por separado. Se ha demostrado que si además del empleo de esas técnicas se emplea un formato de documentación de código similar al de un libro, a fin de dividir el código en piezas que fueran más fáciles de recordar que el listado largo de código, se consigue una visión de alto
13 de 15
07/04/2007 19:18
NeoProgramadores - Cómo Documentar Código con Efectividad
http://www.galeon.com/neoprogramadores/howdocod.htm
fueran más fáciles de recordar que el listado largo de código, se consigue una visión de alto nivel del programa que ayuda mucho a los programadores. El prefacio de un libro puede equiparse con el prólogo de un programa (el bloque de comentarios introductorios que se suele hallar al comienzo de un fichero) puesto que funciona como el primero: ofrece una panorámica del contenido del programa. La tabla de contenido de un libro, dividida en capítulos, puede equiparse al listado de ficheros, clases y rutinas a las que se hace referencia en el programa. Las secciones de un libro se pueden equiparar con las divisiones dentro de las rutinas -declaraciones de rutina, declaraciones de datos y sentencias ejecutables, por ejemplo. Las referencias cruzadas de un libro son los mapas de referencias cruzadas del código, incluyendo números de líneas. Esta analogía permite reducir el tiempo de mantenimiento del código por cuanto permite a los programadores comprender y recordar más fácilmente los distintos componentes de los programas por su familiaridad con la estructura de los libros de texto. Esta analogía da énfasis a la importancia de proveer documentación que explique tanto la organización a alto como a bajo nivel de los programas.
12. Listas de Chequeo para Buenas Técnicas de Documentación Generales ¿Puede alguien ver el código y de inmediato empezar a comprenderlo? ¿Explican los comentarios la intención del código o resumen lo que éste hace, en lugar de sólo repetirlo? ¿Se usa el pseudocódigo para reducir el tiempo de documentación? ¿Se ha reescrito el código truculento en lugar de sobrecomentado? ¿Están los comentarios actualizados? ¿Los comentarios son claros y correctos? ¿Permite el estilo de documentación modificar con facilidad los comentarios? Sentencias y Párrafos ¿Se evitan en el código los comentarios de fin de línea? ¿Se enfocan los comentarios en el por qué en lugar del cómo? ¿Los comentarios preparan al lector del código para lo que sigue? ¿Cuenta cada comentario? ¿Han sido eliminados del código o mejorados los comentarios redundantes, extraños, o caprichosos? ¿Están documentadas las sorpresas? ¿Se han evitado las abreviaturas? ¿Se distinguen claramente los comentarios principales de los secundarios? ¿Está documentado el código que funciona alrededor de un error o de una funcionalidad no documentada? Declaraciones de Datos ¿Están comentadas las declaraciones de variables, estructuras de datos y tipos de datos definidos por el usuario? ¿Están documentados los rangos de valores de las variables y miembros de estructuras de tipos numéricos? ¿Están documentados los significados codificados? ¿Están documentadas las limitaciones de las entradas de datos? ¿Se documenta cada variable y cada estructura de datos global donde se declara o se utiliza? ¿Se identifican las variables y estructuras de datos globales como tales mediante algún tipo de convención, un comentario, o ambos métodos? ¿Se han reemplazado los números mágicos con constantes nombradas o variables en lugar de estar solamente documentadas? Estructuras de Control ¿Está documentada cada estructura de control? ¿Se ha documentado la última línea de cada gran estructura de control, o cuando ha sido posible, simplificado de tal manera que no necesite comentarios? Rutinas ¿Está documentado el propósito de cada rutina? ¿Se brindan en los comentarios de la rutina otros datos relevantes, incluyendo los datos de entrada y salida, las suposiciones de interfaz, limitaciones, corrección de errores, modificaciones a variables y estructuras de datos globales, así como las fuentes de los algoritmos? Ficheros, Clases y Programas ¿Tiene el programa una documentación corta similar a la descrita en la Analogía del Libro que da una visión general de cómo se organiza el programa? ¿Se describe el propósito de cada fichero?
14 de 15
07/04/2007 19:18
NeoProgramadores - Cómo Documentar Código con Efectividad
http://www.galeon.com/neoprogramadores/howdocod.htm
¿Se describe el propósito de cada fichero? ¿Se lista el nombre del autor, su e-mail y su número telefónico dentro del prólogo?
15 de 15
07/04/2007 19:18