Scribd Logo
Cargar

¡Te damos la bienvenida a Scribd!

  • 283 vistas

    Documentación de Código Java

    Cargado por

    wigido
    Este documento describe la importancia de documentar el código y proporciona directrices sobre cómo hacerlo correctamente. Explica que la documentación debe aclarar qué hace el código, por qué y cómo funciona, para facilitar futuras modificaciones o correcciones. Además, detalla los diferentes tipos de comentarios en Java y cuándo y dónde debe añadirse documentación, incluyendo el uso de Javadoc para generar documentación externa de forma automática.

    Copyright:

    Attribution Non-Commercial (BY-NC)
    Descargue como PDF, TXT o lea en línea desde Scribd

    Documentación de Código Java

    Cargado por

    wigido
    283 vistas3 páginas
    Este documento describe la importancia de documentar el código y proporciona directrices sobre cómo hacerlo correctamente. Explica que la documentación debe aclarar qué hace el código, por qué y cómo funciona, para facilitar futuras modificaciones o correcciones. Además, detalla los diferentes tipos de comentarios en Java y cuándo y dónde debe añadirse documentación, incluyendo el uso de Javadoc para generar documentación externa de forma automática.

    Título original

    Documentación de código Java

    Derechos de autor

    © Attribution Non-Commercial (BY-NC)

    Formatos disponibles

    PDF, TXT o lea en línea desde Scribd

    ¿Le pareció útil este documento?

    ¿Este contenido es inapropiado?

    Este documento describe la importancia de documentar el código y proporciona directrices sobre cómo hacerlo correctamente. Explica que la documentación debe aclarar qué hace el código, por qué y cómo funciona, para facilitar futuras modificaciones o correcciones. Además, detalla los diferentes tipos de comentarios en Java y cuándo y dónde debe añadirse documentación, incluyendo el uso de Javadoc para generar documentación externa de forma automática.

    Copyright:

    Attribution Non-Commercial (BY-NC)
    Descargue como PDF, TXT o lea en línea desde Scribd
    Descargar como pdf o txt
    283 vistas3 páginas

    Documentación de Código Java

    Cargado por

    wigido
    Este documento describe la importancia de documentar el código y proporciona directrices sobre cómo hacerlo correctamente. Explica que la documentación debe aclarar qué hace el código, por qué y cómo funciona, para facilitar futuras modificaciones o correcciones. Además, detalla los diferentes tipos de comentarios en Java y cuándo y dónde debe añadirse documentación, incluyendo el uso de Javadoc para generar documentación externa de forma automática.

    Copyright:

    Attribution Non-Commercial (BY-NC)
    Descargue como PDF, TXT o lea en línea desde Scribd
    Descargar como pdf o txt
    Está en la página 1de 3

    Documentacin de cdigo

    1. Introduccin
    Documentar el cdigo de un programa es aadir suficiente informacin como para explicar lo que hace, punto por punto, de forma que no slo los ordenadores sepan qu hacer, sino que adems los humanos entiendan qu estn haciendo y por qu. Porque entre lo que tiene que hacer un programa y cmo lo hace hay una distancia impresionante: todas las horas que el programador ha dedicado a elaborar una solucin y escribirla en el lenguaje correspondiente para que el ordenador la ejecute ciegamente. Documentar un programa no es slo un acto de buen hacer del programador por aquello de dejar la obra rematada. Es adems una necesidad que slo se aprecia en su debida magnitud cuando hay errores que reparar o hay que extender el programa con nuevas capacidades o adaptarlo a un nuevo escenario. Hay dos reglas que no se deben olvidar nunca: 1. todos los programas tienen errores y descubrirlos slo es cuestin de tiempo y de que el programa tenga xito y se utilice frecuentemente 2. todos los programas sufren modificaciones a lo largo de su vida, al menos todos aquellos que tienen xito Un programa, si tiene xito, probablemente ser modificado en el futuro por quien lo codific o por otro programador. Pensando en esta revisin de cdigo es por lo que es importante que el programa se entienda: para poder repararlo y modificarlo.

    2. Qu hay que documentar?


    Hay que aadir explicaciones a todo lo que no es evidente. No hay que repetir lo que se hace, sino explicar por qu se hace

    Y eso se traduce en: de qu se encarga una clase? un paquete? qu hace un mtodo? cul es el uso esperado de un mtodo? para qu se usa una variable o un atributo? cul es el uso esperado de un atributo? qu algoritmo estamos usando? de dnde lo hemos sacado? qu limitaciones tiene el algoritmo? qu limitaciones tiene la implementacin? qu se debera mejorar ... si hubiera tiempo?

    3. Tipos de comentarios
    En Java disponemos de tres notaciones para introducir comentarios:

    Comentarios de una lnea Comienzan con los caracteres "//" y terminan con la lnea Se utiliza para documentar cdigo que no necesitamos que aparezca en la documentacin externa (la que genera javadoc). Este tipo de comentarios se usa incluso cuando el comentario ocupa varias lneas, cada una de las cuales comienza con "//"

    Comentarios de varias lneas Comienzan con los caracteres "/*" y terminan con los caracteres "*/". A menudo e utiliza para eliminar cdigo. Es habitual que el cdigo obsoleto no queremos que desaparezca y lo mantenemos "por si acaso". Para que no se ejecute, se comenta. (En ingls se suele denominar "comment out")

    Comentarios javadoc Comienzan con los caracteres "/**", se pueden prolongar a lo largo de varias lneas (que probablemente comiencen con el carcter "*") y terminan con los caracteres "*/". Se utilizan para generar documentacin externa.

    4. Cundo hay que poner un comentario?


    1. 2. 3. 4. 5. Siempre, al principio de cada clase Siempre, al principio de cada mtodo Siempre, ante cada variable de clase (atributos estticos, constantes). Al principio de un fragmento de cdigo que no resulte evidente. Cuando el programa haga algo raro

    Nota : Cuando un programa se modifica, los comentarios deben modificarse al tiempo, no sea que los comentarios acaben refirindose a un algoritmo que ya no utilizamos.

    5. Javadoc.
    El paquete de desarrollo Java incluye una herramienta, javadoc, para generar un conjunto de pginas web a partir de los ficheros de cdigo. Esta herramienta toma en consideracin algunos comentarios para generar una documentacin bien presentada de clases y componentes de clases (variables y mtodos). Aunque javadoc no ayuda a la comprensin de los detalles de cdigo, si ayuda a la comprensin de la arquitectura de la solucin, lo que no es poco. Se dice que javadoc se centra en la interfaz (API - Application Programming Interface) de las clases y paquetes Java. Javadoc realza algunos comentarios, de los que exige una sintaxis especial. Deben comenzar por "/**" y terminar por "*/", incluyendo una descripcin y algunas etiquetas especiales:

    /** * Parte descriptiva. * Que puede consistir de varias frases o prrafos. * * @etiqueta texto especfico de la etiqueta */

    Estos comentarios especiales deben aparecer justo antes de la declaracin de una clase, un atributo o un mtodo en el mismo cdigo fuente. En las siguientes secciones se detallan las etiquetas (tags) que javadoc interpreta y posteriormente convierte en documentacin. Como regla general, hay que destacar que la primera frase (el texto hasta el primer punto) recibir un tratamiento destacado, por lo que debe aportar una explicacin concisa y contundente del elemento documentado. Las dems frases entrarn en detalles.

    Etiqueta
    @autor nombre @version identificadorDeVersin @since @deprecated

    Dnde se usa
    Clases, interfaces Clases, interfaces Clases, mtodos Clases, mtodos

    Objetivo
    Indicar el autor del cdigo. Se pone una etiqueta por cada autor Informacin acerca de la versin Desde qu versin est. Ej: desde .JDK 1.1 Para indicar que algo no debe utilizarse ya, ha quedado obsoleto, aunque se mantenga por compatibilidad. Se suele acompaar de qu es lo que hay que utilizar el su lugar. Pondr la direccin para conectarse con esta clase en la documentacin Pondr la direccin para conectarse con este mtodo en la documentacin. Para describir los valores devueltos por cada mtodo y su tipo. Excepciones que el mtodo puede elevar. Se pone una etiqueta para cada excepcin posible. Se suelen ordenar alfabticamente. Para describir los parmetros, su utilizacin y su tipo. Se pone una etiqueta para cada parmetro

    @ see ClassName @see ClassName#NombreMtodo @return descripcin @exception nombre descripcin

    Clases, interfaces, mtodos y atributos. Clases, interfaces, mtodos y atributos. Mtodos Mtodos

    @param nombre descripcin

    Mtodos

    6. Referencias
    Sun proporciona material de cmo documentar las interfaces de los programas:

    http://java.sun.com/j2se/javadoc/writingdoccomments/
    (How to write doc comments for the javadoc tool)

    También podría gustarte