Términos generales

Documentación

Palabras clave

Comentarios, técnicas para comentar, documentación interna.

1. INTRODUCCION

El siguiente documento contiene una descripción de varias técnicas para realizar comentarios. En cada una de ellas se mencionan sus ventajas y desventajas. El objetivo es dar al lector una perspectiva de qué son buenos comentarios y porque son necesarios.

2. COMENTAR O NO

   Esta pregunta ha traído muchas discusiones entre programadores, ya que los malos comentarios dificultan el trabajo. Pero la verdad es que buenos comentarios pueden prestar mucha ayuda a la hora de depurar el código y a la hora de hacerlo (ya verá por qué).

   Características de un buen comentario

   • NO REPITE EL CODIGO!!!!!

   • Explica la INTENCION del código.

   • No es exageradamente largo, ni le falta información.

   • Tiene un estilo fácil de modificar.

   Algunos autores dan recomendaciones como éstas:

   • “No llene su código con comentarios de bajo nivel línea por línea.”^[2]

   • “Los comentarios son necesarios como párrafos explicativos.”^[3]

   Mal comentario:

   // set product to "base"
   
   product = base;// loop from 2 to "num"
   
   for ( int i = 2; i <= num; i++ ) {
   
      // multiply "base" by "product"
   
      product = product * base;
   
   }
   
   System.out.println("Product = " + product);

   Buen comentario:

   // compute the square root of Num using the Newton-Raphson approximation
   
   r = num / 2;
   
   while ( abs( r - (num/r) ) > TOLERANCE ) {
   
      r = 0.5 * ( r + (num/r) );
   
   }
   
   System.out.println( "r = " + r );

3. TECNICAS PARA COMENTAR

   • Enfóquese en el por qué más que en el cómo.

   • Prepare al lector para lo que sigue.

   • Haga que cada comentario valga la pena.

   • Documente sorpresas.

   • Eluda abrviaciones.

   • Diferencie entre comentarios mayores y menores.

   • Comentar cualquier error o usos indocumentados en un lenguaje o ambiente de desarrollo.

   • Justifique las violaciones de un estilo de programación adecuado.

   • No comente código malo, reescríbalo.

Comentarios de lineas individuales

Normalmente no se debe usar ya que es difícil decir algo útil sobre una sola línea de código. Las únicas razones válidas para usarlos es que el código de una línea sea muy complicado y no se pueda hacer más entendible o que la línea antes haya tenido un error y se quiera hacer un record del mismo (para lo cual es mejor tener un registro de errores a parte de todas formas).

Comentarios de final de línea

A veces son útiles, pero usualmente presentan problemas. A menos que se alineen a la derecha del código con tabs hacen ver el código desordenado y no son fáciles de identificar. Alinearlos a la derecha del código es problemático y hace que sea necesario modificarlos si una línea que tenga uno es modificada.

Estos comentarios no se deben usar para notas de mantenimiento, ni para múltiples líneas de código. Sólo deben ser usados para líneas individuales en el caso de que se quiera documentar declaraciones o marcar el final de bloques de código.

Ejemplo de uso correcto:

int boundary = 0;         // upper index of sorted part of arrayString insertVal = BLANK; // data elmt to insert in sorted part of array

int insertPos = 0;        // position to insert elmt in sorted part of array

Comentarios de bloques

Estos comentario siempre deben explicar la intención o el propósito del párrafo del bloque de código que le sigue. Deben decir cosas que el código mismo no puede. A pesar de que estos comentarios dan muchas explicaciones es mejor mantenerlos cortos haciendo un mayor esfuerzo en que el código mismo se documente y no en los comentarios.

Algunas pautas a tener en cuenta:

Comentarios de declaraciones de datos

En las declaraciones debeme documentar las unidades y el rango de datos numéricos, los números en nombres de variables que representan un código que no se entiende sin comentar, limitaciones de entradas de usuario, variables con significado en cada bit y variables globales.

Comentarios de estructuras de control

Las estructuras de control deben documentarse para indicar su propósito y el motivo de su elección. Cada estructura debe tener una explicación de su función precediéndola y un comentario al final indicando su terminación.

Ejemplo de comentarios de marca de terminación:

for ( tableIndex = 0; tableIndex < tableCount; tableIndex++ ) {

   while ( recordIndex < recordCount ) {

      if ( !IllegalRecordNumber( recordIndex ) ) {

         ...

      } // if

   } // while

} // for

Comentarios de rutinas

Las rutinas se deben comentar siempre. No se deben hacer grandes headers con mucha información, los que a veces son más largos que el mismo código. Un buen comentario de rutinas contiene los elementos mencionados en la sección 6 en template para módulos. No es necesario usar siempre todos los campos, sólo se usan si son necesarios.

Comentarios de files, classes y programas

Las clases, los files y los programas se caracterizan por tener múltiples rutinas. Siempre, las rutinas agrupadas, deben tener una relación estrecha. Esto es lo que se debe documentar, un resumen del contenido de las rutinas. Una forma fácil para hacerlo es pensar en el motivo por el que se pusieron juntas. Para buenos comentarios siga la guía de los templates en la sección 6.

4. CODIGO AUTODOCUMENTADO

“Se ha propuesto que la mejor solución al problema de documentación es usar lenguajes autodocumentados.”^[2] Desde la aparición de los lenguajes de alto nivel es posible escribir nombres de rutinas, datos, estructuras, clases y archivos entendibles para seres humanos. Usar nombres sencillos y descriptivos hace la lectura del código mucho más fácil.

Los comentarios deben ser sólo una herramienta para decir lo que no se puede decir en el código. Los lenguajes de programación son eso mismo, lenguajes, expresan instrucciones a seguir. Si alguien conoce el lenguaje, debe ser capaz de entender lo que dice, por lo tanto no es necesario decírselo en otro lenguaje. Debemos decirle en otro lenguaje, solamente lo que no puede entender si lee sólo el código. En el libro hemos aprendido como escribir nuestro código para que otros lo entiendan, ésta es la mejor solución para que otros disfruten la lectura de nuestros programas.

Ejemplo:

Código mal escrito:

for ( i = 2; i <= num; i++ ) {

meetsCriteria[ i ] = true;

}

for ( i = 2; i <= num / 2; i++ ) {

j = i + i;

while ( j <= num ) {

meetsCriteria[ j ] = false;

j = j + i;

}

}

for ( i = 1; i <= num; i++ ) {

if ( meetsCriteria[ i ] ) {

System.out.println ( i + " meets criteria." );

}

}

Código bien escrito:

for ( primeCandidate = 2; primeCandidate <= num; primeCandidate++ ) {

   isPrime[ primeCandidate ] = true;

}for ( int factor = 2; factor < ( num / 2 ); factor++ ) {

    int factorableNumber = factor + factor;

    while ( factorableNumber <= num ) {

        isPrime[ factorableNumber ] = false;

        factorableNumber = factorableNumber + factor;

    }

}

for ( primeCandidate = 1; primeCandidate <= num; primeCandidate++ ) {

   if ( isPrime[ primeCandidate ] ) {

      System.out.println( primeCandidate + " is prime." );

   }

}

5. USO DE PSEUDOCODIGO

El pseudocódigo trae muchas ventajas a la hora de programar. Primero que todo, es una herramienta útil para diseñar rutinas y clases. Escribir el pseudocódigo hace que el programador piense bien lo que quiere lograr y permite que cada línea de código que se escriba tenga un propósito específico y conocido, uno que el programador tiene bien claro; tanto que es capaz de escribirlo en su idioma. Además de esto, a la hora de terminar el código, los comentarios ya están ahí. Tenga en cuenta que la parte del pseudocódigo que dice exactamente lo que hace el código es reemplazada por éste, no se deja, ya que no agregaría nada útil al mismo.

6. USO DE TEMPLATES

   Para documentar rutinas, clases y archivos es posible utilizar guías para saber qué es lo que debemos escribir. A continuación hay varios ejemplos de templates para documentación:

   Template para módulos:

   • Propósito del módulo (una o dos oraciones).

   • Fecha de revisión.

   • Limitaciones y restricciones del algoritmo usado.

   • Descripción de datos de entrada y salida.

   • Suposiciones que deben ser tomadas en cuenta.

   • Tipos de errores y procedimientos de recuperación.

   • Efectos globales de la rutina.

   Template para clases:

   • Descripción del diseño utilizado.

   • Limitaciones y suposiciones.

   • Descripción de la interface para el usuario.

   Template para files:

   • Propósito y contenido del file.

   • Nombre, email y teléfono del autor.

   • Control de versiones.

   • Noticias legales y políticas de uso.

Nota: cada elemento del template se debe usar sólo si es necesario para la rutina. Por ejemplo, no debe describir errores, si no hay errores en esa rutina.

7. REFERENCIAS

1. McConnell, S. Code Complete, Microsoft Press, 2004.

2. Martin, J., McClure, C. Software Maintenance: The Problem and its Solutions, Prentice-Hall, 1983.

3. Marca, D., Applying Software Engineering Principles, Little Brown and Company, 1984.

4. King, D. Current Practices in Software Development, Yourdon Press, 1984.

5. Aron, J. D. The Program Development Process, Addison-Wesley, 1974.

Los tamaños de cada tipo en C y C++ no son siempre iguales. Estos tamaños, no sólo dependen de la arquitectura de la computadora en la que se esté compilando, sino del compilador usado y a veces hasta del sistema operativo en el que se está compilando.

Esto es algo que afecta la portabilidad del lenguaje ya que puede producir errores en el código cuando se compila en diferentes entornos. A pesar de esto si hay un mínimo en el tamaño de cada tipo, que, sin importar el entorno, siempre va a ser igual. Estos son:

char——————-8 bits

short int————–16 bits

int———————16 bits

long int—————32 bits

float——————-32 bits

double—————-64 bits

long double———-64 bits

Estos tamaños son el mínimo aceptado para cada tipo, pero pueden variar con el compilador, el sistema operativo y la arquitectura. Algunas herramientas que ayudan al manejo de tipos son el include <stdint.c> que permite especificar el tamaño de int que se quiere usar y el ‘AC_CHECK_SIZEOF’ macro por GNU, que permite especificar los tamaños por medio de typedef.

1. INTRODUCTION

Una permutación es un arreglo (lista) de objetos en un orden específico. Un arreglo de n elementos puede tener diversas permutaciones, cada permutación se distingue de otra por el lugar que ocupan los elementos en esta. Por ejemplo en el arreglo [n] = {1, 2, 3, …, n}, el 1 ocupa el primer lugar, el 2 el segundo y así sucesivamente hasta llegar a n. En cambio la siguiente es una permutación distinta que la anterior ya que el 2 ocupa la primera posición y el 1 la segunda [n] = {2, 1, 3, …, n}.

2. FACTORIAL Y PERMUTACIONES

Factorial

El factorial es una operación matemática denotada por n!. Donde n! = n(n-1)(n-2)…(2)(1). Eso signifca que 3! = 3(2)(1) = 6. La única permutación que no se puede definir así es la de 0 que es 0! = 1.

Cantidad de permutaciones diferentes

La cantidad de permutaciones de un número n de elementos es igual a n!. Eso significa que la cantidad de permutaciones diferentes de un arreglo de 4 elementos es igual a 4! = 24.

3. NOTACION

Hay diferentes formas de notación para expresar permutaciones indicando los cambios que se realizan a un primer arreglo de elementos. Sólo presento tres, esto no implica que no haya mas.

Lista de Inversiones

En una lista de inversiones (a₁, …, a_n) a_i representa el número de elementos mayores que i que están a la izquierda de i. Por ejemplo la siguiente lista de inversiones (2 3 6 4 0 2 2 1 0) construye la permutacón de (5 9 1 8 2 6 4 7 3) de la siguiente manera: Empezamos con el 9. Luego como a8 dice 1 escribimos 9 8. El siguiente dice 2 por lo tanto es 9 8 7. El elemento a6 dice 2, por lo que el 6 sólo tiene 2 elementos a su izquierda, entonces 9 8 6 7. Y así sucesivamente hasta llegar a (5 9 1 8 2 6 4 7 3).

Ciclos

Los ciclos representan los números que cambian unos con otros, formando al final ciclos de cambios. Como ejemplo representaremos una permutación del siguiente arreglo (1 2 3 4). Si el ciclo es (2 3 4) (1) eso implica que el uno no cambia con nadie, el dos cambia con el tres, el tres con el cuatro y el cuatro con el dos. Des esta manera nuestro arreglo queda ( 1 4 2 3).

Matriz

La matriz simplemente representa en una matriz de 2 x n los arreglos en su orden antiguo y nuevo.
Ej:

1 2 3

2 1 3

4. ORDEN

Lexicográfico

El orden lexicográfico es el orden en el que más fácil pensamos cuando vemos permutaciones y queremos organizarlas. En este orden los número cambian de posiciones de dos en dos cada vez. Todas las combinaciones con el primer valor aparecen primero, luego el segundo valor, luego el tercero, el cuarto y asi sucesivamente hasta n. Igual pasa con las permutaciones dentro de ella. Los elementos en una posición menor siempre se quedan ahí hasta que se realizan todas las permutaciones con los elementos en una posición mayor que ellos. Ej: (1 2 3), (1 3 2), (2 1 3), (2 3 1), (3 1 2), ( 3 2 1)

De transposición

Es un orden en el que cada permutación siguiente difiere de la anterior por la transposición de dos elementos adyacentes. Hay diferentes formas de lograr este orden. Por eso un mismo arreglo puede tener diferentes ordenes de transposición. Por ejemplo: 123, 132, 312, 321, 231, 213

5. REFERENCIAS

1. ACM, Collected Algorithms from ACM, 71, 86, 102, 202

2. Knuth, Donald, Fundamental Algorithms

3. Skiena, Steve S., The algorithm Design Manual

4. Oosterwal, Erik, All Permutations Routine, http://www.geocities.com/oosterwal/computer/combinations.html

5. Recombining Permutations,

   http://www.cut-the-knot.org/Curriculum/Combinatorics/PermOnCircle.shtml

6. Permutation, http://mathworld.wolfram.com

7. Finite-Geometry Models,

   http://www.cut-the-knot.org/do_you_know/permutation.shtml#permutation