Ant 2e6 + 1

Comentarios: esos grandes desconocidos

jbautistam — Thu, 27 Sep 2007 09:35:36 +0000

Los comentarios dentro del código sirven para explicar las funciones de una serie de instrucciones y facilitar la lectura del código.

Sin embargo existen ciertos comentarios que no aportan nada a la documentación del código y que de hecho pueden resultar molestos y contraproducentes. Por ejemplo:

Private Sub cmbo_pnt_SelectedIndexChanged(ByVal sender As Object, ByVal e As System.EventArgs) Handles cmbo_pnt.SelectedIndexChanged
    cmbo_grupo_farma.Enabled = True
    cmbo_grupo_farma.Focus()
    envia_aviso(1)
 
            'lbl_ayuda.Visible = False
            'lbl_ayuda.Visible = False
            'lbl_ayuda.Text = ""
 
            'cmbo_pnt.Enabled = False
            'cmbo_pnt.Visible = False
 
    'module_uno.pnt_conf = (cmbo_pnt.Text.Trim)
            'corro_barra()
 
    'Dim c_mc As New col_muestras_confirmar.col_muestras_confirmar
            '' c_mc.solicito_confirmacion()
    'c_mc = Nothing
 
    'If module_uno.pnt_conf <> "PNT-CO-03" Then
            '    solicito_alicuota(module_uno.pnt_conf)  ' Solicito para el pnt de confirmación
    'Else
            '    If pnt_co_03 = False Then
            '        solicito_alicuota(module_uno.pnt_conf)
    '    End If
    'End If
 
            'If module_uno.pnt_conf = "PNT-CO-03" Then pnt_co_03 = True
 
 
            'lst_sustancias.Items.Add(module_uno.pnt_conf & "-" & module_uno.dis_producto)
 
    'If module_uno.pnt_conf <> "PNT-CU-07" Then
            '    limpia_eleccion()
    'End If
 
    'If module_uno.pnt_conf = "PNT-CU-07" Then
            '    reconfiguro_formulario()
    'End If
    '' Si el procedimiento es pnt-co-03
    'If module_uno.pnt_conf = "PNT-CO-03" Then
 
    'End If
End Sub

El noventa por ciento de esta función lo ocupan una serie de comentarios. En realidad son instrucciones comentadas. Pero ¿por qué están comentadas? ¿Son pruebas? ¿Es parte del código que ya no se necesita? ¿Es parte necesaria del código pero se ha comentado para arreglarla más adelante?

Cuando una serie de código no sea ya necesaria por cualquier motivo, la mejor opción no es comentarla si no eliminarla. Así evitamos que posteriormente surjan dudas de este tipo. Si lo que queremos es volver a consulta el código que hemos eliminado siempre podemos ir a la aplicación de gestión de código fuente (SourceSafe) y consultar las versiones anteriores.

Eso además evita construcciones de este tipo:

Private Sub cmd_aceptar_Click(ByVal sender As System.Object, ByVal e As System.EventArgs)
    ' Debemos de chequear que haya por lo menos una opción elegida.
            If lst_sustancias.Items.Count > 0 Then
                    descarga_solicitudes()
                    Dim c_mc As New col_muestras_confirmar.col_muestras_confirmar
                    '   c_mc.descarga_confirmaciones()
                    c_mc = Nothing
                    module_uno.confirma_mta = True
            Else
                    module_uno.envia_message(38)
            End If
    End Sub

En la línea 5 se define un objeto, en la línea 7 se destruye y en la línea 6 que supuestamente lo utilizaba se ha comentado el código por lo que realmente nunca se utiliza el objeto que hemos creado. ¿Por qué se ha comentado? y los más importante ¿por qué se han dejado sin comentar la creación y la destrucción del objeto?

Aparte de los comentarios que “generan dudas” en lugar de “solucionar dudas” están los comentarios ligeramente inútiles:

//***************************************************************************
//*  PROYECTO           :   ReportViewer
//*  VERSIÓN            :   1.0
//*  MÓDULO/PROGRAMA    :   frmReportViewer
//*  NOMBRE             :
//*  LENGUAJE           :   C# (C Sharp)
//*  TIPO               :   Clase
//*  FECHA CREACIÓN     :   10/06/2007
//*  FECHA MODIFICACIÓN :
//*  AUTORES            :   Pedro Naranjo
//*
//*
//*  MODIFICADO POR     :
//*  DESCRIPCIÓN        :   Visor de Informes de SQL Server 2005 Reporting Service
//*  COMENTARIOS        :   Para su correcto funcionamiento necesita las tablas:
//*                         MENUS_CONFIGURACION, MENUS_ITEMS y MENUS_PERFIL
//*                         y el procedure: P_MENUS_PERFIL_Select_By_MEP_PERFIL_ID
//****************************************************************************

Estos comentarios, aunque visualmente atractivos, no aportan realmente ninguna información. El nombre del proyecto lo sabemos a partir del nombre de archivo, el lenguaje a partir del propio código, las fechas de creación y modificación se pueden obtener a partir de las fechas de archivo y el autor a partir de la aplicación de gestión de código fuente.

Lo único que aporta algo es la descripción y los comentarios finales, el resto se puede obtener de otras fuentes y no deberían aparecer en el código.

Del mismo modo que este tipo de comentarios:

//****************************/
//*    V A R I A B L E S     */
//****************************/

Queda bonito pero para el programador que lea el código seguramente le bastaría con una única línea que le indicase que se van a definir variables locales. Cuando se está leyendo código es interesante tener el máximo número de líneas ejecutables posible en la pantalla, tres líneas para un comentario, a mí al menos, me resulta una pérdida de espacio y en este caso de tiempo para formatear el aspecto del comentario.

Normalización de código

jbautistam — Fri, 31 Aug 2007 08:37:10 +0000

En el diseño de interfaces de usuario existe un concepto denominado “minimizar el aturdimiento”. Imaginemos por un momento un editor de texto en el que el icono del botón Grabar no represente un disco si no un hombre prehistórico cincelando una piedra. La primera vez que el usuario escriba su documento y desee grabarlo irá a buscar el botón de grabar, lo más lógico sería que buscase un disco y seguramente tarde un tiempo en encontrar el botón adecuado. Cuando se diseña un interface de usuario se busca que sea similar a otras aplicaciones: los botones de grabar contienen la imagen de un disco, los de nuevo documento una hoja en blanco, los de formato en negrita una B mayúscula (o una N si están en inglés)… Se intenta constantemente que cuando el usuario se enfrente por primera vez a la aplicación encuentre un entorno familiar, que no se “aturda”, en tres palabras: “minimizar el aturdimiento”.
¿Qué tiene que ver esto con la normalización de código? En nuestro trabajo el 90% del tiempo lo pasamos viendo diverso tipo de código, de diferentes aplicaciones o de diferentes módulos de la misma aplicación. Lo normal es que al cabo del tiempo veamos tanto código propio como de nuestros compañeros de equipo, cada archivo con un estilo diferente (incluso aunque provenga del mismo programador), distintas tabulaciones, diferentes formas de nombrar las variables, todo esto implica que nos lleve un tiempo más o menos largo poder leer el código y saber lo que está haciendo y un tiempo aún más largo ser capaces de modificarlo. En resumen: estamos tan “aturdidos” como el usuario al que hemos cambiado los gráficos de los botones.

Parte del trabajo, quizá el más importante, de la normalización del código es precisamente minimizar las diferencias de trabajo y proporcionar un entorno sensato para que el periodo de adaptación sea mínimo y facilite tanto la programación de nuevo código como el mantenimiento del antiguo. En pocas palabras, nuestro esfuerzo se dirige a minimizar el aturdimiento producido al leer código.

Nombres de variables: unicidad y significado

Imaginemos que tenemos una serie de funciones en un programa en C# que graban los datos de un pedido, antes de ello, calcula el saldo a partir de las líneas:

   1: public void Save(clsPedido op)

   2: { ComputeLines(op);

   3:   op.Save();

   4: }

5:

   6: public void ComputeOrder(clsPedido o)

   7: { o.Saldo = ComputeLines(o);

   8: }

9:

  10: public int ComputeLines(clsPedido ope)

  11: { colLineas op = ope.LoadLines();

12:

  13:     return ope.SumLines();

  14: }

En el código anterior, las tres funciones utilizan una clase que mantiene el pedido (clsPedido), sin embargo, las tres funciones llaman a sus variables de forma diferente, en la primera se llama op, en la segunda o y en la tercera ope. Además, la tercera función utiliza de nuevo la variable op pero no para nombrar una variable de tipo clsPedido si no para identificar una variable de tipo colLineas.

El programa es corto, no existe demasiado espacio para la confusión, pero ya hemos utilizado tres nombres de variables diferentes, cada vez que entremos a modificar una función tendremos que buscar cómo se llama la variable que identifica nuestro pedido antes de poder siquiera empezar a pensar en modificarla.

La solución en este caso es muy sencilla, si vamos a utilizar una variable para identificar un objeto lo lógico es utilizar siempre el mismo nombre de variable:

   1: public void Save(clsPedido op)

   2: {   ComputeLines(op);

   3:     op.Save();

   4: }

5:

   6: public void ComputeOrder(clsPedido op)

   7: { op.Saldo = ComputeLines(op);

   8: }

9:

  10: public int ComputeLines(clsPedido op)

  11: { colLineas ol = op.LoadLines();

12:

  13:     return ol.SumLines();

  14: }

En esta ocasión sabremos que la variable que representa nuestro pedido se llama op mientras que la variable que representa las líneas se llama ol. Con algo tan simple hemos conseguido dos cosas fundamentales: en primer lugar que cada vez que entramos a una función sabemos cómo se llaman nuestras variables, en segundo lugar, si entramos en otra parte del programa y encontramos una variable denominada op podemos llegar a suponer que se trata de un objeto relacionado con un pedido. Esto además nos lleva a un efecto lateral que facilita un poco más el trabajo: evitamos pensar cómo tenemos que llamar un nuevo objeto de tipo clsPedido cuando creemos una nueva función, la elección es simple: se llamará op.

Por supuesto tenemos un pequeño problema, op es fácil de escribir y ligeramente sencillo de recordar pero tiene un significado cuando menos difuso, se podría referir también a la clase clsProveedor, por ejemplo. Debemos intentar que nuestros nombres tengan significado, que nos digan algo. ¿Y si en lugar de utilizar op como nombre de variable para la clase clsPedido utilizáramos algo más significativo como por ejemplo objPedido? Con este cambio conseguimos que el código sea más legible y más fácil de recordar.

Además podemos establecer una norma: inicialmente todos los nombres de objetos comenzarán por el prefijo obj y les seguirá el nombre de la clase a la que se representa. Así para la clase clsPedido tendremos variables que se llamarán objPedido, para la clase clsProveedor variables con el nombre objProveedor, para la clase clsCliente variables con el nombre objCliente.

Pero ¿qué ocurre cuando en una función utilizamos más de una variable de una clase? No podemos definir dos veces un nombre de variable idéntico dentro de la misma función pero sí podemos añadir un sufijo a esa variable para que nos amplíe el significado. Así por ejemplo si tenemos una función en la que se copien los datos de un pedido en otro podemos utilizar los nombres de variables objPedidoOrigen y objPedidoDestino:

   1: public void Copy(clsPedido objPedidoOrigen, clsPedido objPedidoDestino)

   2: { objPedidoDestino.Precio = objPedidoOrigen.Precio;

   3:   objPedidoDestino.Unidades = objPedidoOrigen.Unidades;

   4: }

De esta forma además de identificar nuestra variable y saber que objPedidoOrigen es de tipo clsPedido puesto que sigue nuestra normativa de nombres, también sabemos que es la fuente de los datos mientras que objPedidoDestino representa el pedido sobre el que se van a copiar los datos.

Hola mundo!

jbautistam — Fri, 18 Aug 2006 07:36:04 +0000

De acuerdo, el título del envío lo dice todo: soy programador. Sobre todo programador. Además analista y jefe de proyecto en ciernes pero lo que más me gusta es programar.

En mi blog por tanto intentaré hablar de tres temas principales: programación, arquitectura de software y dirección de proyectos, aunque no descarto hablar también de tecnología en general, aplicaciones, software libre, etc…

Por supuesto se aceptan críticas, nuevos temas y sobre todo comentarios.