En primer lugar ¿que es la documentación?
La documentación es una guía detallada acerca de como funciona funciona nuestro código, estructura, y como utilizarlo.
¿Para que nos sirve esto?
- Permite la reutilización del código sin tener que entenderlo a la perfección.
- Al intentar darle mantenimiento a tu código la documentación vuelve mas sencilla esta tarea.
- Compartir tu código para que cualquiera pueda sacarle provecho.
- Si se trabaja con un grupo de personas estas no tendrán que tocar tu código para saber como funciona.
¿ Como hacemos una documentación?
Para lograr esto hay muchas herramientas que hacen mas sencilla la tarea por ejemplo : Doxygen, AdaDoc(para ada), Cxref (documentacion para C), Latex, pascdoc, etc.
Aquí por causalidad me tope con esta pequeña lista de herramientas para documentar:
Si Estas trabajando en java como yo, java ya nos proporciona una herramienta para crear documentacion en formato html esta herramienta es "JavaDoc".
Para crear una documentacion por medio de javadoc se escribe lo que se desea documentar dentro de un comentario que inicia con "/**" y termina con "*/" dentro de estas se puede poner HTML o etiquetas que normalmente inician con un "@" (por lo general son elementos básicos de un código), por ejemplo:
{ /** Esto es un ejemplo de como hacer una documentacion.
* @author Max Hernandez :D
* @version la version de este programa.
*/
public class ejemplo{
/**
Este es el método mas importante del codigo :p
@param args Este es el parametro de mi código pero seguro que el tuyo tendra mas
*/
public static void main(String[] args){
System.println("Soy un ejemplo");
}
}
Sugerencias.
- Los comentarios deben ser lo mas concisos y lo mas precisos posibles.
- Marcas las palabras clave.
- Lo ideal es que tengo la documentación tenga la información suficiente para saber como funciona o para que sirve cada: clase, cada método de cada clase, cada parámetro, cada bloque de código que pueda causar duda.
Aquí una lista de tags de javadoc de la pagina oficial de java:
Un poquito más específico te hubiera ganado puntos completos. Esto te da 4.
ResponderBorrar