Cursos Empresas Blog Live Conf Eventos Precios

0:0011:42

Recursos

Resumen

¿Cómo documentar un proyecto con JavaDocs?

Al comenzar un proyecto de software, es esencial contar con una documentación clara y precisa que permita a cualquier desarrollador comprender el alcance, las funcionalidades y las reglas de negocio del mismo. Una práctica recomendable es utilizar JavaDocs para generar esta documentación de manera estandarizada. Veamos cómo aplicar esta técnica a nuestro proyecto de manera efectiva.

¿Cómo estructurar la información de la clase principal?

La clase principal, que contiene el punto de entrada del proyecto, es el lugar ideal para comenzar a documentar tu aplicación. Aquí hay algunos pasos a seguir:

Usar el encabezado H1: Esto ayuda a definir el título del proyecto y su propósito general.

/**
 * <h1>Amazon Viewer</h1>
 * Amazon Viewer es un programa que permite visualizar movies, series, books y magazines.
 * Te permite generar reportes generales y con fecha del día.
 */

Proveer una descripción general: Detalla brevemente qué hace el programa, las características clave y las reglas generales que sigue.
Añadir etiquetas de autor y versión: Esto es crucial para el mantenimiento del proyecto.
```
* @author And
* @version 1.1
* @since 2018
*/
```

¿Cómo documentar clases abstractas?

La documentación de clases abstractas, como Film, sigue una estructura similar pero necesita enfatizar su carácter genérico:

Describir el carácter abstracto: Usa @code para resaltar métodos abstractos.

/**
 * <h1>Film</h1>
 * Film es una clase padre abstracta que representa la base de la familia de Film.
 * <p>Esta clase contiene el método abstracto {@code view} obligatorio de implementar.</p>
 * @author And
 * @version 1.1
 * @since 2018
 */

Mencionar métodos abstractos: Asegúrate de indicar claramente qué métodos deben ser implementados por las subclases.

¿Cómo añadir comentarios a interfaces y métodos?

La interfaz, como Visualizable, puede documentarse para indicar cómo debe ser utilizada:

Documentar métodos: Incluye información sobre los parámetros y los valores de retorno.

/**
 * Este método captura el tiempo exacto de visualización.
 * @param date Es un objeto de tipo {@code Date} con el tiempo exacto.
 * @return Devuelve la fecha y hora capturada.
 */

Describir parámetros y retornos: Usa @param y @return para especificar lo que recibe y devuelve un método.

Este enfoque de documentación no solo facilita la comprensión de cómo utilizar una clase o un método, sino que también mejora la mantenibilidad del código a largo plazo, permitiendo a diferentes desarrolladores trabajar en el mismo proyecto de manera eficiente. Por supuesto, es importante que cada sección de documentación sea clara y precisa para ser verdaderamente útil. No te olvides de que la práctica y consistencia te ayudarán a dominar la generación de documentación efectiva. ¡Sigue aprendiendo y mejorando tus habilidades!

Documentación en Java: Uso de Etiquetas y Comentarios HTML

Curso Avanzado de Java SE

Clase 7 de 40

Clase 7 / 40

Juan Carlos Barcinilla Alarcon

Hace 7 años

Implemente mi propio código y clase.

/*
 * To change this license header, choose License Headers in Project Properties.
 * To change this template file, choose Tools | Templates
 * and open the template in the editor.
 */
package com.simple.pap.models;

import com.simple.pap.controllers.LeerPropiedad;
import java.sql.SQLException;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.sql.DataSource;
import java.sql.Connection;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import oracle.jdbc.pool.OracleDataSource;

/**
 * <h1>ConfigDb</h1>
 * <p>
 * Esta Clase abstracta extenderan todas las clases hija donde se quiera
 * realizar la conexcion a base datos. Ademas tienes un metodo
 * {@code systemIsWindows()} metodo que devuelve true si es sistemas y
 * {@code ruta()} metodo que devuelve la ruta donde esta desplegada la
 * aplicacion. windows.
 * </p>
 *
 * @author eforero
 * @version 1.0
 * @since 2018
 */
public abstract class ConfigDB {

    protected Connection conPosgress;
    protected Connection conMultiUsua;
    protected DataSource odsPosgrest;
    protected OracleDataSource ods;
    DataSource ds = null;

    /**
     * <h1>abrirConexionPG</h1>
     * <P>
     * Metodo que abre la conexion a base de datos de posgrest
     * </P>
     *
     * @author eforero
     * @version 1.0
     * @since 2018
     */
    public void abrirConexionPG() {

        try {
            Context ctx = new InitialContext();
            odsPosgrest = (DataSource) ctx.lookup(LeerPropiedad.leerPropiedades().getProperty("url.datasource.posgrest"));
            conPosgress = odsPosgrest.getConnection();
        } catch (SQLException | NamingException ex) {
            Logger.getLogger(ConfigDB.class.getName()).log(Level.SEVERE, null, ex);
        }
    }

    /**
     * <h1>cerrarConexionPG</h1>
     * <P>
     * Metodo que cierra la conexion a base de datos de posgrest
     * </P>
     *
     * @author eforero
     * @version 1.0
     * @since 2018
     * @author juan.barcinilla
     * @version 2.0
     * @since 2019-05-27
     */
    public void cerrarConexionPG() {
        try {
            if (!conPosgress.isClosed()) {
                conPosgress.close();
            }
        } catch (SQLException ex) {
            Logger.getLogger(ConfigDB.class.getName()).log(Level.SEVERE, null, ex);
        }
    }

    /**
     * <h1>conectarMultiusua</h1>
     * <P>
     * Metodo que abre la conexion a base de datos de Oracle
     * </P>
     *
     * @author eforero
     * @version 1.0
     * @since 2018
     * @author juan.barcinilla
     * @version 2.0
     * @since 2019-05-27
     */
    public void conectarMultiusua() {
        try {
            Context ctx = new InitialContext();
            ods = (OracleDataSource) ctx.lookup(LeerPropiedad.leerPropiedades().getProperty("url.datasource.oracle"));
            conMultiUsua = ods.getConnection();
        } catch (NamingException | SQLException ex) {
            Logger.getLogger(ConfigDB.class.getName()).log(Level.SEVERE, null, ex);
        }
    }

    /**
     * <h1>cerrarConexionMultisua</h1>
     * <P>
     * Metodo que cierra la conexion a base de datos de Oracle
     * </P>
     *
     * @author eforero
     * @version 1.0
     * @since 2018
     */
    public void cerrarConexionMultisua() {
        try {
            if (!conMultiUsua.isClosed()) {
                conMultiUsua.close();
            }
        } catch (SQLException ex) {
            Logger.getLogger(ConfigDB.class.getName()).log(Level.SEVERE, null, ex);
        }
    }

    /**
     * <h1>systemIsWindows()</h1>
     * <P>
     * Metodo que devuelve verdadero si el sistema operativo windows
     * </P>
     *
     * @author juan.barcinilla
     * @version 1.0
     * @since 2018
     * @return {@code boolean }
     */
    private boolean systemIsWindows() {
        return System.getProperty("os.name").startsWith("Windows");
    }

    /**
     * <h1>ruta()</h1>
     * <P>
     * Metodo que devuelve la ruta donde esta desplegada la aplicacion.
     * </P>
     *
     * @author juan.barcinilla
     * @version 1.0
     * @since 2018
     * @return {@code boolean }
     * @see {@code systemIsWindows()}
     */
    public String ruta() {
        String ruta;
        if (systemIsWindows()) {
            ruta = "C:\\Data\\archivo-pap";//PRUEBA LOCAL
        } else {
            ruta = "/media/archivo-pap";//PRODUCCION
        }
        return ruta;
    }

}

Comentarios (25)25 comentarios

César David Ramírez Dimaté

Hace 8 años

Raul Castillo

Buen aporte.

JUAN SEBASTIAN RODRIGUEZ JIMENEZ

Gracias, buen aporte.

Luisa Fernanda Leguizamón Bayona

Hace 6 años

Hola Todos. Para que automáticamente se coloquen los parámetros del método, se coloca /** y se da ENTER antes de la firma.

Arturo Munoz Cantor

PERFECT... SO IS !!!

Noe de Jesus Muñoz Martinez

Excelente clase de como documentar en Java.
Resumen:
En la clase Main:

/**
 * <h1>AmazonViewer</h1>
 * AmazonViewer es un programa que permite visualizar Movies, Series con sus respectivos Chapters, Books y Magazines.
 * Te permite generar reportes generales y con fecha del día.
 * <p>
 * Existen algunas reglas como todos los elementos pueden ser visualizados o leídos a excepción 
 * de las Magazines, estas sólo pueden ser vistas a modo de exposición sin ser leídas.
 * 
 * @author njmunoz
 * @version 1.1
 * @since 2019
 * */

En la clase Film

/**
 * <h1>Film</h1>
 * Film es una clase padre abstracta.
 * <p>
 * Es la clase base de la familia Films, como es abstracta no se puede instanciar y por ende contiene el método abstracto
 * {@code view()} que es obligatorio implementar para todo aquél que pertenezca a la familia.
 * 
 * @author njmunoz
 * @version 1.1
 * @since 2019
 * */

En el método abstract view de la clase Film:

/**
* {@code view()} es un método abstracto obligatorio de implementar.
 * */

En la clase IVisualizable:
Método startToSee:

/**
* Este método captura el tiempo exacto de inicio de visualización.
 * 
 * @param dateI Es un objeto {@code Date} con el tiempo de inicio exacto.
 * @return {@code Date} Devuelve la fecha y hora capturada.
 * */

Método stopToSee:

/**
* Este método captura el tiempo exacto de inicio y final de visualización.
* 
* @param dateI Es un objeto {@code Date} con el tiempo de inicio exacto.
* @param dateF Es un objeto {@code Date} con el tiempo final exacto.
* */

Francisco Prado

Recomiendo leer el capitulo 4 de libro Codigo Limpio de Robert C. Martin, toda una catedra!!!
_
“No hay nada mas util que un comentario bien colocado. No hay nada que colapse más un modulo que comentarios dogmaticos innecesarios. No hay nada mas dañino que un comentario antiguo que propague mentiras y desinformacion…”_ Robert C. Martin

Daniel Meza

Estaría genial un curso, aplicando convenciones de código limpio en nuestros proyectos.

Jose Luis Marin Escamilla

Lo voy a leer.

José Gálvez

Me encantó la explicación, soy de los que comentan todo y tener una forma de presentar esas explicaciones como documentación me parece genial.

NICOLAS ZAPATA ALZATE

Se adelantó el vídeo en la parte de “Hereda” en la clase Movie en el minuto 11:11.

Cristian Ortega

Es cierto, es como si hubieran cortado una parte de la clase.

Lo hace es porque más adelante lo pone como un reto, de cómo hacer javadocs para herencias e interfaces.

Carlos Andres Carvajal

En el minuto 11:11, iba a adicionar este comentario en la case Movie

/**
 * Hereda de {@link Film}
 * Implementea de {@link IVisualizable}
 * */

Iba a adicionar este comentario en la clase Movie, minuto 11:11

Yossijaki Jorge Astilleros Chávez

Excelente, solo me confundi un poco cuando vas a comentar el de Movie (hereda) pero ya vi que lo aclararas en la proxima clase.

Misael Pereira Diaz

En IDEs como IntelliJ y sus Derivados solo con poner /** y presionar enter les crea el JavaDocs

Andres Lopez

Hace un año

creonque autor no es tan necesario en este scope, ya que git puede ayudar mucho más con blame.

KEVIN Cordon

Hace 4 años

muy buena explicacion de como se impletementa java docs

Ronald Amiquero Zoiqui

¿Porque la etiqueta de párrafo <p> no se cierra como la etiqueta <h1>? Muchas gracias por sus respuestas

En la sintaxis de HTML5, existen muchísimas etiquetas que no necesitan obligatoriamente etiqueta de cierre, aunque contengan a otros elementos dentro.

Muchas de ellas, además son de lo más común. Por ejemplo los párrafos, las listas, casi todos los elementos de las tablas, y por supuesto las propias etiquetas <html> y <body> que, de hecho, se pueden omitir por completo si queremos.

Norman Erick Estrada Vargas

excelente explicación!!!

Eduardo Flores

Pregunta, ¿Es necesario implementar el javadoc en absolutamente todos los métodos, incluso en los getters y setters?, Lo pregunto por que he visto algunos proyectos que lo hacen pero en lo personal creo que eso puede se exagerado.

Jair Israel Avilés Eusebio

Depende, en realidad no es necesario documentar todos los metodos.

Eso dependerá de los requerimientos del proyecto, a veces sobre el proyecto se deben de pasar informes de calidad del código (SonarQube) que puede requerir cierto porcentaje de código comentado.

Cambia muy rapido de pestaña, un poco más de tiempo para ver como queda el comentario seria fenomenal. :P

Paul Cortes

Muy buena clase sobre como usar los JavaDocs

Daniel Arturo Dominguez Lopez

quedo muy claro como usar javadocs

Rafael Carrillo

Muy interesante las etiquetas de documentación de java docs

Recursos

Resumen

Documentación en Java: Uso de Etiquetas y Comentarios HTML

Progreso del curso

Introducción al Curso

Clases avanzadas

JavaDocs

Clases Anidadas

Interfaces Avanzadas

Colecciones Avanzadas

Excepciones

JDBC

Lambdas

Fin del Curso