Documentar el código

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";
      }
      

      coment04coment05

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

def45-7-2-1
Java

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

coment06.png

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.

coment07.png

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.

coment08.png

 

Anuncios

Atajos Netbeans

Atajos Netbeans

Todos los IDE,s tienen una serie de mejoras que nos ayudan a escribir código de manera fácil y evitando errores, en este caso Netbeans no podía ser menos.

¿Que son los atajos de Netbeans? Son palabras que nos permiten escribir bloques de código de una manera rápida evitando repetir estructuras continuamente. Lo primero de todo que son muy prácticos y lo segundo que evitan muchos errores, (causan otros), pero creo que las ventajas son muy superiores a los pocos inconvenientes que pudiera tener. Para el que no esté familiarizado con el código, lo mejor sería teclear todas las instrucciones letra por letra y olvidarse de los atajos por una temporada hasta que controléis la mayoría de las instrucciones. Hay dos tipos, uno mediante combinación de teclas y otros escribiendo palabras + TAB.

Las combinaciones de teclas, pueden visualizarse en los menús y menús contextuales. Alguno de los ejemplos de combinación de teclas:

  • CTRL + SPACE→ o completa la palabra que estamos intentando escribir o nos muestra una lista con las sugerencias.
  • ALT + ENTER→ Si nuestro código se encuentra subrayado en rojo, nos muestra que podemos hacer. Si instanciamos Scanner y no tenemos importado java.util.Scanner, al combinar sobre este nos mostrará lo mismo que si pulsamos sobre la bombilla de sugerencias.
  • CTRL + R→Imaginad que tenemos una variable en 20 sitios distintos, pues si nos situamos sobre ella y usamos este atajo, nos resalta todas las variables en el código pudiendo detectarlas con más facilidad.
  • ALT + SHIFT+ F →Da formato al código
  • CTRL + E → Borra líneas de código CTRL+ SHIFT+ Flecha Arriba o Abajo →Copia líneas de código
  • ALT + SHIFT+ Flecha Arriba o Abajo →Sube o baja líneas de código
  • CTRL + SHIFT + B. Navega hasta la fuente del código.
  • CTRL + B. Navega hasta la declaración
  • ALT + F7. Busca todas las referencias usadas en los proyectos abiertos
  • F6. Ejecuta el proyecto
  • CTRL + F5. Ejecuta en modo depuración

Ejemplos de palabras + TAB.

atajos01También es posible usar CTRL + SPACE cuando estemos escribiendo alguna de estas palabras y nos mostrará las sugerencias. Todos estos atajos están al principio de la lista marcados con un icono cuando pusalmos CTRL + SPACE

  • sout + TAB → System.out.println(“”)
  • soutv + TAB → System.out.println(“this = ” + this);
  • serr + TAB → System.err.println(“”);
  • for +TAB → for (int i = 0; i < 10; i++) { }
  • forc + TAB → for (Iterator iterator = col.iterator(); iterator.hasNext();) {Object next = iterator.next();}
  • fore + TAB → for (String arg : args) { }
  • whilexp +TAB → while (true) { }
  • do +TAB → do { } while (true);
  • if +TAB → if (true) { }
  • ifelse +TAB → if (true) { } else { }
  • sw +TAB → switch (var) { case val: break; default: throw new AssertionError(); }
  • trycatch → try { } catch (Exception e) { }

una vez que los escribimos, hay que tener en cuenta que algunos de ellos debemos completarlos (de ahí los posibles errores). Por ejemplo, sw que genera el bloque de código switch hay que escribir el valor de la variable y los valores de cada caso, si no el código nos daría error. El bloque de código fore, se debe indicar la colección o forc hay que indicar el iterator.

Espero que os sirva de ayuda aunque reitero que si no estáis familiarizados con el código hay que escribirlo mil veces hasta que nos suene antes de usar atajos.