documentación de código

IBUNIKE.COM

NEWS

No. 05 / MAGAZINE

MARZO2013

Comentario

FormatoUsos

Herramientas para documentar código

Generación de documentación

Manuales

13 Consejos para comentar tu código

Contenido

¿Que es?

4

Documentación de Código

Definición

5

Comentario

De los Comentarios

6

Formato / Usos

¿Cómo?

12

Generación de documentación

Algunas...

13

Herramientas para documentarcódigo

¡¡¡Sorprendete !!!

18

13 Consejos para comentar tucódigo

¡¡¡Para documentar!!!

24

Manuales

IbuNike

Editorial

Información

Somos un equipomultidisciplinario dealto perfil profesionalque ha motorizadocambios de granimpacto y aportespara la comunidad enel medio informativoimpreso, al tiempoque ha posicionado aesta Corporacióncomo líder en latransmisión de lainformación entiempo real a travésde Internet,ofreciendo unexcelente vehículopara el mensaje denuestros anunciantes.

Nuestra Visión

Capturar nuevas audiencias de contenido buscando unaposición de liderazgo en mercados hispano parlantes conproductos innovadores, de alta calidad y rentables,mediante la generación eficiente de contenidomultimedia, la efectiva gestión de audiencias y laexcelencia de nuestra gente.

IbuNike 3

Documentación deCódigo

D

ocumentar el código de un programa es añadir suficienteinformación como para explicar lo que hace, punto por punto, deforma que no sólo los ordenadores sepan qué hacer, sino queademás los humanos entiendan qué están haciendo y por qué.

“lo que tiene que hacer un programa y cómolo hace hay una distancia impresionante.”

Documentar un programa no es sólo un acto de buen hacer delprogramador por aquello de dejar la obra rematada. Es además una necesidadque sólo se aprecia en su debida magnitud cuando hay errores que reparar ohay que extender el programa con nuevas capacidades o adaptarlo a un nuevoescenario. Hay dos reglas que no se deben olvidar nunca:

1. todos los programas tienen errores y descubrirlos sólo es cuestión detiempo y de que el programa tenga éxito y se utilice frecuentemente.

2. todos los programas sufren modificaciones a lo largo de su vida, al menostodos aquellos que tienen éxito.

Por una u otra razón, todo programa que tenga éxito será modificado en elfuturo, bien por el programador original, bien por otro programador que lesustituya. Pensando en esta revisión de código es por lo que es importante queel programa se entienda: para poder repararlo y modificarlo.

IbuNike 4

Comentarios

E

n programación, un comentario es una construcción del lenguajede programación destinada a incrustar anotaciones legibles alprogramador en el código fuente de un Programa informático.

“Estas anotaciones son potencialmentesignificativas para los programadores.”

... pero usualmente ignorados por los compiladores e intérpretes. Loscomentarios son añadidos usualmente con el propósito de hacer el códigofuente más fácil de entender con vistas a su mantenimiento o reutilización. Lasintaxis y reglas para los comentarios varían y usualmente son definidas en laespecificación del lenguaje de programación.

Se ha de tener en cuenta que los comentarios necesitan mantenimientoigual que el código y, por tanto, que un comentario preciso y conciso es másfácil de mantener que uno largo, repetitivo y complicado.

Los comentarios tienen una amplia gama de posibles usos: desde la mejoradel código fuente con descripciones básicas hasta la generación dedocumentación externa. También se utilizan para la integración con sistemasde control de versiones y otros tipos de herramientas de programaciónexternas. La flexibilidad proporcionada por los comentarios da pie a un amplioabanico de formas de uso distintas y a la inclusión de información inútildentro del código fuente. Para evitar este inconveniente, muchosprogramadores y analistas de software adoptan alguna de las "filosofías" ometodologías para la correcta utilización de los comentarios.

IbuNike 5

“Formato.”

Los comentarios adoptan por normageneral un formato de "bloque"(también denominado de "prólogo") ode "fin de línea" (también denominado"inline").

Un comentario de bloque delimita unazona del código fuente en la cual espermitido expandirse a varias líneas detexto. Esta región se reconoce por undelimitador de inicio y un delimitadorde final del comentario. Algunoslenguajes de programación admitenque los comentarios se anidenrecursivamente pero otros lenguajesno lo admiten.

Un comentario de fin de líneacomienza con un delimitador ycontinúa hasta el final de la línea detexto (es decir, no es necesario unsegundo delimitador). En otros casos,el comentario de fin de línea comienzaen una cierta columna dentro delcódigo fuente no siendo necesario undelimitador.

Los delimitadores son una secuenciaconocida de caracteres y suelen serdistintos para los comentarios debloque que para los de fin de línea.

Por ejemplo, el lenguajeC++ usa, para loscomentarios de bloque, losdelimitadores /* y */mientras que loscomentarios de fin de líneautiliza el delimitador //.Otros lenguajes solamenteadmiten un tipo decomentario. Por ejemplo,ADA solamente dispone decomentarios de fin de líneamediante el delimitador --.

IbuNike 6

Usos

Planeación / Revisión

Los comentarios se pueden utilizarcomo una forma de pseudocódigo paradescribir la intención antes de escribirel código real. En este caso se debeexplicar la lógica detrás del código enlugar del código en sí mismo.

/* itera hacia atrás por todos loselementos retornados por el servidor(estos deben ser procesadoscronológicamente)*/ for (i = (numElementsReturned - 1); i>= 0; i--){ /* procesa los datos de cada elemento*/ updatePattern(i,returnedElements[i]); }

Si se deja este tipo de comentario luegode escribir el código, se simplifica elproceso de revisión al permitir lacomparación directa del código con losresultados previstos.

IbuNike 7

Usos

Descripción de Código

Los comentarios pueden ser utilizadospara resumir el código o para explicarla intención del programador. Segúnesta escuela de pensamiento, re-explicar el código en lenguaje naturalse considera superfluo y la necesidadde volver a explicar el código puede serun signo de que es demasiadocomplejo y debe ser reescrito.

"No documentes mal código – re-escríbelo.". "Los buenos comentariosno repiten el código, ni lo explican.Estos aclaran su intención. Loscomentarios deben explicar, a un nivelde abstracción más alto que el propiocódigo, lo que se intenta conseguir"

Los comentarios también pueden serutilizados para explicar por qué unbloque de código no se ajusta a lasconvenciones o las buenas prácticas.Esto está especialmente relacionadocon proyectos de escaso tiempo dedesarrollo, o en la corrección deerrores. ' Se asigna una segunda variabledebido a que se producen errores ' en el servidor cuando se reutilizan losdatos del formulario. No se encontródocumentación ' sobre el comportamiento extraño delservidor, así que simplemente secodificó para resolverlo. vtx = server.mappath("local settings")

IbuNike 8

Usos

Descripción Algorítmica

A veces, el código fuente contiene unasolución nueva o digna de mencionarsea un problema específico. En talescasos, los comentarios puedencontener una explicación de lametodología. Estas explicacionespueden incluir diagramas y pruebasmatemáticas formales. Esto puede serla explicación del código, en lugar deuna clarificación de sus intenciones,pero otros encargados delmantenimiento del código puedenencontrar como fundamental estaexplicación.

Esto puede ser especialmente cierto enel caso de problemas de dominios dealta especialización; así como enoptimizaciones, construcciones ollamadas a funciones de uso nocotidiano. Por ejemplo, unprogramador puede agregar uncomentario para explicar por qué seeligió un Ordenamiento por inserciónen lugar de quicksort, pues el primeroes, en teoría, más lento que el segundo.Esto podría escribirse de la siguientemanera:

list = [f (b), f (b), f (c), f (d), f (a), ...];

// Se requiere un ordenamientoestable, mientras el desempeñorealmente no importa.

insertion_sort (list);

IbuNike 9

Usos

Inclusión de recursos

Logotipos y diagramas de flujoconsistentes en construcciones de arteASCII pueden ser insertados en elcódigo fuente en forma de comentario.Además, puede incrustarse comocomentarios avisos de derechos deautor, fecha de creación, versión delproducto, contacto con el propietarioy/o creador.

El fragmento de código que sigue es unsimple diagrama ASCII que representael flujo de proceso para un script deadministración de sistemas contenidoen un Fichero Windows Script que seejecuta en Windows Script Host Apesar de que la sección que marca elcódigo aparece como un comentario, eldiagrama de hecho aparece en unasección XML CDATA sección, quetécnicamente se considera distinta delos comentarios, pero que puede servirpara propósitos similares.

IbuNike 10

Usos

Depuración

Una práctica común entreprogramadores es comentar unfragmento de código, es decir, agregardelimitadores de modo que un bloquede código se convierta en uncomentario, y por tanto no se ejecutaráen el programa final. Esto podríahacerse para excluir algunas piezas delcódigo del programa o, de manera máscomún, para encontrar la causa de unerror. Comentando sistemáticamente yejecutando partes del programa, lacausa del error puede ser determinada,permitiendo su corrección. Acontinuación un ejemplo de cómocomentar código con el propósito deexcluirlo:

if (opt.equals ("e")) opt_enabled = true; /* if (opt.equals ("d")) opt_debug = true; // */ //* if (opt.equals ("v")) opt_verbose = true; // */

El fragmento de código de arribasugiere que el programador optó pordesactivar la opción de depuración poralguna razón. Este estilo específico decomentario es más adecuado para ladepuración. Un carácter de barrasimple delante del delimitador deapertura es el que permite habilitar odeshabilitar el comentarios de bloquecompleto.

IbuNike 11

GeneraciónDe Código

L

as herramientas de programación en ocasiones incorporandocumentación y metadatos en los comentarios.

“Estos comentarios de control funcional sonconocidos comúnmente como anotaciones.”

Mantener la documentación dentro de comentarios en el código fuente esconsiderado como una forma de simplificar el proceso de documentación, asícomo un aumento en las posibilidades de que la documentación se mantendráal día con los cambios en el código.

Habitualmente este tipo de comentarios requiere utilizar una sintaxis básicapara que puedan ser interpretados por el generador de documentación adiferencia de los comentarios anteriores donde no necesariamente se debe deutilizar una sintaxis predefinida.

Ejemplos de generadores de documentación son el programa javadoc,diseñado para ser utilizado con el lenguaje de programación Java, Ddoc parael lenguaje de programación D y doxygen, para ser usado con C/C++, JavaIDL y PHPDoc para PHP.

C#, F# y Visual Basic implementan una característica similar llamadacomentarios XML, que son leídos por IntelliSense para los ensambladoscompilados del entorno.NET.

IbuNike 12

Herramientas paradocumentar Código

JavaDoc: Documentación deAPIs

El paquete de desarrollo Java incluyeuna herramienta, javadoc, para

generar un conjunto de páginas web apartir de los ficheros de código. Estaherramienta toma en consideración

algunos comentarios para generar unadocumentación bien presentada de

clases y componentes de clases(variables y métodos).

“Javadoc realza algunos comentarios, de losque exige una sintaxis especial.”

Aunque javadoc no ayuda a lacomprensión de los detalles de código,

si ayuda a la comprensión de laarquitectura de la solución, lo que noes poco. Se dice que javadoc se centra

en la interfaz (API - ApplicationProgramming Interface) de las clases y

paquetes Java.

Deben comenzar por "/**" y terminarpor "*/", incluyendo una descripción y

algunas etiquetas especiales.

IbuNike 13

Herramientas ParaDocumentar

Código

Doxygen

Es un programa que analiza el códigoen busca de directivas en forma de

comentarios y las transforma endocumentación, bien HTML, bien

LaTeX e incluso podemos crear unapágina de manual de linux para

visualizar con el mítico comando"man". Doxygen acepta multitud de

lenguajes como C/C++ o Java. Laprincipal ventaja de Doxygen es sin

duda que las directivas no son más quecomentarios de forma que no tenemosque crear una documentación aparte,

sino, simplemente, comentar el código.

“PhpDocumentor, Se puede utilizar desde lalínea de comandos o una interfaz web”

PhpDocumentor

Es un generador de documentación decódigo abierto escrito en PHP.

Automáticamente analiza el códigofuente PHP y produce la API de lecturay documentación del código fuente en

una variedad de formatos.phpDocumentor genera la

documentacion en base al estándarformal PHPDoc.

Es compatible con la documentacióndel código orientado a objetos y

programación procedural, además escapaz de crear documentos HTML,PDF, CHM y formatos Docbook.

IbuNike 14

Tiene soporte para la vinculación entre la documentación,la incorporación de documentos a nivel de usuario comotutoriales, y la creación de código fuente resaltado con

referencias cruzadas a la documentación en general de PHP.phpDocumentor es capaz de analizar toda la sintaxis dePHP y apoya PHP4 y PHP5. Se trata de un proyecto de

código abierto y se distribuye bajo la licencia LGPL.

Lorem Ipsum

Estilos

Hay muchas alternativas cuando seconsidera como los comentarios debenaparecer en el código fuente. Paragrandes proyectos, los estilos de loscomentarios se agregan apenascomienzan el proyecto. Normalmentelos programadores prefieren estilosque son consistentes, no obstructivos,fáciles de modificar, y difíciles deromper.

Los siguientes fragmentos de código enC son solo un ejemplo de como loscomentarios pueden variar de estilo,mientras todos contienen la mismainformación básica:

/* Este es el cuerpo del comentario.Variante 1*//***********************************\ * * * Este es el cuerpo del comentario. ** Variante 2. ** *\************************************/

Factores tales como la preferenciapersonal, la flexibilidad de lasherramientas de programación, y otrasconsideraciones tienden a influir en lasvariantes de estilo utilizado en elcódigo fuente.

IbuNike 16

Etiquetas

Algunas etiquetas se utilizan en loscomentarios para ayudar en laindexación de los problemas comunes.Tales etiquetas son comúnmenteresaltadas de sintaxis y permitebúsquedas con herramientas deprogramación común, como la utilidadgrep de UNIX. Ejemplos de conveniosetiqueta son:

FIXME: para marcar códigoproblemático potencial que requiereuna atención especial y/o revisión.

NOTE: peligros potenciales paradocumentar el funcionamiento internodel código y de indicar.

TODO: para indicar las mejorasplanificadas.

XXX: para advertir a otrosprogramadores de código problemáticoo equivoco.

Existe el riesgo de que las etiquetas seacumulen con el tiempo, esconveniente incluir la fecha y elpropietario de etiqueta en elcomentario de etiquetas para facilitarel seguimiento.

IbuNike 17

13 Consejos paraComentar tu Código

IbuNike 18

1. Comenta a varios niveles

Comenta los distintos bloques de losque se compone tu código, aplicandoun criterio uniforme y distinto paracada nivel. Puedes, por ejemplo, seguirun modelo como:

• En cada clase, incluir una brevedescripción, su autor y fecha de últimamodificación • Por cada método, una descripción desu objeto y funcionalidades, así comode los parámetros y resultadosobtenidos

En realidad, lo importante es ceñirse aunas normas (comúnmente aceptadassi se trata de trabajo en equipo) yaplicarlas siempre. Las reglasconcretas pueden ser elegidas a laconveniencia de cada cual.

Obviamente, una solución bastanteaceptable e incluso aconsejable esutilizar las convenciones yherramientas que ayudan y facilitanesta tarea.

"Consejos para Comentar"

2. Usa párrafos comentados

Como complemento al punto anterior,es recomendable dividir un bloque decódigo extenso en "párrafos" querealicen una tarea simple, e introducirun comentario al principio de formaque se guíe al lector, precediéndolos,además, de una línea en blanco queayude a separar cada uno del anterior.

3. Tabula por igual los comentarios delíneas consecutivas

Si tenemos un bloque de líneas decódigo donde existe por cada una deellas un comentario, es buenacostumbre tabularlos todos a la mismaposición, de forma que quedaránalineados y serán más sencillos de leer,sobre todo si forman parte de la mismafrase. Ojo a las tabulaciones.

IbuNike 19

Hay editores que usan el carácterASCII (9) y otros, en cambio, losustituyen por un númerodeterminado de espacios, que suelenvariar según las preferenciaspersonales del desarrollador. Lo mejores usar espacios simples o asegurarsede que esto es lo que hace el IDEcorrespondiente.

4. No insultes la inteligencia del lector

Debemos evitar comentarios absurdoscomo: if (a == 5) // Si a vale cinco, ... counter = 0; // ... ponemos el contadora cero Este exceso necesita mucho tiempo a lahora de su creación, lo necesitará parasu mantenimiento y, además, lamayoría de las veces distraerá al lectorcon detalles que no es necesarioconocer o que pueden ser deducidosechando un vistazo al código.


5. Sé correcto

Evita comentarios del tipo "ahoracompruebo que el estúpido usuario nohaya introducido un número negativo",o "este parche corrige el efectocolateral producido por la patéticaimplementación del ineptodesarrollador inicial".

El uso de este tipo de comentarios nodice nada a favor de su creador, y,además, nunca se sabe quién los va aleer en el futuro. Emarts, en "Sapos,culebras y código fuente" muestraejemplos de comentarios de este tipo.

Otro tema relacionado igualmenteimportante: cuida la ortografía. Elhecho de que los comentarios no sevean desde el exterior no implica quepuedas descuidarlos. Una ortografíacorrecta mejora la calidad de laexpresión escrita y, por tanto, de lacomunicación, que es de lo que setrata.

IbuNike 20

6. No pierdas el tiempo

No comentes si no es necesario, noescribas nada más que lo que necesitespara transmitir la idea. Nada dediseños realizados a base de caracteresASCII, ni florituras, ni chistes, nipoesías, ni chascarrillos. En resumen,mantén los comentarios simples ydirectos, pues de lo contrario harásperder tiempo a tu sucesor.

7. Utiliza un estilo consistente

Hay quien opina que los comentariosdeberían ser escritos para que losentendieran no programadores. Otros,en cambio, piensan que debe servir deayuda para desarrolladoresexclusivamente.


8. Para los comentarios internos usamarcas especiales

Y sobre todo, aunque no únicamente,cuando se trabaja en un equipo deprogramación en el que variaspersonas pueden estar tocando lasmismas porciones de código. En estecaso los comentarios no se usan paraexplicar una porción de código, sinopara realizar anotaciones sobre elmismo a las que hay que prestarespecial atención. Eso sí, si usas estatécnica, recuerda que debesactualizarlos conforme las anotacionesdejen de tener sentido.

9. Comenta mientras programas

Ve introduciendo los comentariosconforme vas codificando. No lo dejespara el final, puesto que entonces tecostará más del doble de tiempo, si esque llegas a hacerlo. Olvida lasposturas "no tengo tiempo decomentar, voy muy apurado", "elproyecto va muy retrasado"... sonsimplemente excusas. Si tu intenciónes comentar el código, no te engañes y¡hazlo!

IbuNike 21

"Consejos paraComentar"

H

ay incluso quien opina que los comentarios que describen unbloque deberían escribirse antes de codificarlo, de forma que, enprimer lugar, sirvan como referencia para saber qué es lo que hayque hacer y, segundo, que una vez codificado éstos queden comocomentarios para la posteridad.

“Lorem ipsum dolor sit amet, si dici consectetuer adipisci elit integre.”

10. Comenta como si fuera para ti mismo. De hecho, lo es.

A la hora de comentar no pienses sólo en mantenimiento posterior, ni creasque es un regalo que dejas para la posteridad del que sólo obtendrá beneficiosel desarrollador que en el futuro sea designado para corregir o mantener tucódigo. En palabras del genial Phil Haack, "tan pronto como una línea decódigo sale de la pantalla y volvemos a ella, estamos en modo mantenimientode la misma"

Como consecuencia, nosotros mismos seremos los primeros beneficiaros (ovíctimas) de nuestro buen (o mal) hacer.

11. Actualiza los comentarios a la vez que el código

De nada sirve comentar correctamente una porción de código si en cuanto éstees modificado no se actualizan también los comentarios. Ambos debenevolucionar paralelamente, pues de lo contrario estaremos haciendo másdifícil la vida del desarrollador que tenga que mantener el software, alfacilitarle pistas incorrectas para comprenderlo.

Atención especial a las refactorizaciones automáticas, que suelen introducircambios en distintos puntos del código de un proyecto, dejando loscomentarios obsoletos en ese mismo instante.

IbuNike 22

12. La regla de oro del código legible

He dejado para el final uno de losprincipios básicos para muchosdesarrolladores: deja que tu códigohable por sí mismo. Aunque sesospecha que este movimiento estáliderado por programadores a los queno les gusta comentar su código ;-), estotalmente cierto que una codificaciónlimpia puede hacer innecesaria laintroducción de textos explicativosadicionales.

13. Difunde estas prácticas entre tuscolegas

Obviamente, aunque ya hemoscomentado en el punto 10 que nosotrosmismos nos beneficiamosinmediatamente de las bondades denuestro código comentado, lageneralización y racionalización de loscomentarios y la creación código claronos favorecerá a todos, y sobre todo encontextos de trabajo en equipo. Nodudes, por tanto, en crear cultura decomentarios en tu entorno.

IbuNike 23

Manuales1) Manual Del usuario

E

xpone los procesos que el usuario puede realizar conel sistema implantado. Para lograr esto, es necesarioque se detallen todas y cada una de las característicasque tienen los programas y la forma de acceder eintroducir información.

Permite a los usuarios conocer el detalle de qué actividades ellos deberándesarrollar para la consecución de los objetivos del sistema. Reúne lainformación, normas y documentación necesaria para que el usuario conozca yutilice adecuadamente la aplicación desarrollada.

Objetivos

-Que el usuario conozca cómo preparar los datos de entrada. -Que el usuario aprenda a obtener los resultados y los datos de salida. -Servir como manual de aprendizaje. -Servir como manual de referencia. -Definir las funciones que debe realizar el usuario. -Informar al usuario de la respuesta a cada mensaje de error.

Pasos a seguir para definir como desarrollar el manual de usuario.

Identificar los usuarios del sistema: personal que se relacionará con el sistema.Definir los diferentes tipos de usuarios: se presentan los diferentes tipos deusuarios que usarían el sistema. Ejemplo: usuarios directos, indirectos. Definirlos módulos en que cada usuario participará: Se describen los módulos oprocesos que se ejecutarán por cada usuario en forma narrativa breve y clara.

IbuNike 24

Importancia

E

l Manual de Usuario facilita el conocimiento de:

-Los documentos a los que se puede dar entrada por computadora. -Los formatos de los documentos. -Las operaciones que utiliza de entrada y salida de los datos. -El orden del tratamiento de la computadora con los datos introducidos. -El momento en que se debe solicitar una operación deseada. -Los resultados de las operaciones realizadas a partir de los datosintroducidos.

Al elaborar el Manual de Usuario, hay que tener en cuenta a quién va dirigidoes decir, el manual puede ser manejado desde el director de la empresa hastael introductor de datos. Por consiguiente, debe redactarse de forma clara ysencilla para que lo entienda cualquier tipo de usuario.

Contenido

Diagrama general del sistema

Muestra en forma condensada el flujo general de la información y de lasactividades que se realizan en el sistema. Proporciona una visión general delsistema. Representar los diagramas utilizando para ello diagramas debloques.

IbuNike 25

Diagrama Particular detallado

Presentar gráficamente todos los pasosque se efectúen dentro deldepartamento usuario a quien estádirigido este manual. Debenespecificarse los archivos de entrada,salida, los resultados, revisiones yprocesos manuales.

Explicación genérica de las fases delsistema

Se explica en forma específica ydetallada todas las operaciones queaparecen representadas en formagráfica en el diagrama particular. Seanalizan cada una de las fasesseñalando:

-El proceso principal que sedesarrolla. -La entrada de la información. -La obtención de un resultado parcial. -El envío de información a otradependencia.

Instalación del sistema

La instalación del sistema proporcionadetalles completos sobre la forma deinstalar el sistema en un ambienteparticular.

Inicialización del uso del sistema

En este punto se explica cómo iniciarseen el sistema y cómo se pueden utilizarsus cualidades comunes. Estadocumentación debe decir al usuariocómo salir de un problema cuando lascosas funcionan mal.

IbuNike 26

Manuales2) Manual De Referencia

E

s el documento definitivo de cara al usuario y debe ser completo.Describe con detalle las cualidades del sistema y su uso, losinformes de error generados y las situaciones en que surgen esoserrores.

Dependiendo del sistema, los documentos al usuario se puedenproporcionar por separado o reunidos en varios volúmenes. Lossistemas de ayuda en línea evitan que el usuario pierda tiempo enconsultas manuales.

Caducidad De Documento Fuente Y Destino Final

Como el usuario trabajará con documentos fuentes, éstos podrántener un período de retención y un destino especificado.

IbuNike 27

documentación de código

Documents