Documentar el código

El código además de ser limpio, legible, entendible o estructurado entre otras características, debe estar muy bien documentado con el fin de efectuar un mantenimiento, modificación o ampliación de nuestra fuente. Además, es posible generar documentación en base a estos comentarios como es el caso de JavaDoc.

Existen muchas formas de comentar el código, por ejemplo:

C#, Java, PHP, etc.

• Solo C#. Podemos hacerlo con tres barras /// en la que al crear una nueva línea, la siguiente línea queda también comentada con ///. Si las escribimos antes de una clase o un método, genera etiquetas de comentario que expondré a continuación.
• Dos barras, crea una línea de código comentado
• Comentario multilínea. Una barra y un asterisco /* provoca que el código esté comentado hasta que se cierre el comentario con asterisco barra */

Visual basic.NET

• Comillas simples para comentar línea. ‘Esto es un comentario en VB.NET
• Usar la etiqueta REM. REM Esto es un comentario en VB.NET
• Si queremos crear varias líneas, debemos usar el concatenador guión bajo

  REM Esto es un comentario_ 
  en VB.NET

HTML

• para cerrar el comentario

Comentarios de clases y métodos

Cuando estamos escribiendo código e instanciamos una clase o seleccionamos un método de una clase, los IDE,s nos muestran una ayuda que nos muestra que hace el método, que parámetros tiene o que sobrecargas y esto se consigue del siguiente modo:

C#

• • Escribimos /// precediendo a una clase o un método y se generan automáticamente una serie de etiquetas xml. La documentación de las etiquetas la pueden encontrar en el siguiente enlace.

    /// <summary>
    /// Obtiene el nombre completo del objeto Persona
    /// </summary>
    /// <param name="dni">DNI del objeto persona</param>
    /// <returns>Cadena de texto con el nombre completo</returns>
    public string GetFullName(string dni)
    {
    	return "Joaquín Martínez;
    }
    
    /// <summary>
    /// Obtiene el nombre completo del objeto Persona
    /// </summary>
    /// <param name="id">Identificador del objeto persona</param>
    /// <returns>Cadena de texto con el nombre completo</returns>
    public string GetFullName(int id)
    {
    	return "Joaquín Martínez;
    }
    

    

    

    

Java

• • Escribimos encima de un método /** e INTRO y se genera las etiquetas para documentar el código

    /**
    * Obtiene el nombre completo del objeto Persona
    * @param dni DNI del objeto persona
    * @return Cadena de texto con el nombre completo
    */
    public String getFullName(String dni){
    	return "Joaquín Martínez";
    }
    
    /**
    * Obtiene el nombre completo del objeto Persona
    * @param id Identificador del objeto persona
    * @return Cadena de texto con el nombre completo
    */
    public String getFullName(int id){
    	return "Joaquín Martínez";
    }
    

    

Regiones

Otra forma de mantener el código ordenado es mediante regiones, esto nos va a permitir por ejemplo mantener en una clase de negocio los métodos de actualización, adición y eliminación separados de los de selección, mantener propiedades en una región, campos en otra, métodos públicos en otra, privados en otra y así cuantas regiones queramos tener con el fin de mantener el código ordenado. Yo personalmente en una clase, generalizando, siempre tengo una región para constructores y destructores, una para enumeraciones, una para campos, una para métodos públicos y protected, otra para privados y si la clase es un form o window, añado una para controles y dentro de esta, por tipo de control, añado métodos de evento de cada uno, por ejemplo, Buttons, DataGrid, etc.

C#

#region Métodos públicos
        // aquí podemos poner todos los
        // miembros de clase que queramos
#endregion

VB.NET

#Region "Métodos Públicos"
' aquí podemos poner todos los
' miembros de clase que queramos
#End Region

Java

// <editor-fold desc="Métodos públicos" defaultstate="collapsed">
        // aquí podemos poner todos los
        // miembros de clase que queramos
// </editor-fold>

Tareas

Visual Studio tiene comentarios de tareas, es decir si incluimos una serie de comentarios específicos (TOKEN) en alguna parte del código con un comentario adicional, en la lista de tareas, podemos acceder a esta localización de código para continuar con la tarea pendiente. Estos Token pueden personalizarse en el Menú Herramientas, Opciones, Lista de tareas. En este ejemplo, he colocado un TOKEN para revisar el contenido del método y en la lista de tareas, al hacer doble click, nos dirigiremos al código en cuestión.

Hay que añadir y es una buena costumbre, documentar las clases con autoría, fechas de creación y modificación, que hace la clase, que función tiene, las modificaciones que se han realizado, etc.

Hacedme caso, un poco tiempo perdido en documentar, nos hará ganar muchísimo tiempo en un futuro.