Comentarios: esos grandes desconocidos

¿Cómo se deben escribir comentarios en nuestro código fuente?


Comentarios: esos grandes desconocidos

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 no necesitemos ciertas líneas de código por cualquier motivo, la mejor opción no es comentarlas si no eliminarlas. Así evitamos que posteriormente surjan dudas de este tipo. Si lo que queremos es volver a consultar el código que hemos eliminado siempre podemos ir a la aplicación de gestión de código fuente 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 la 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 xxxx
//*
//*
//*  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.

Algo similar sucede con este tipo de comentarios:

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

Puede que quede 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.

Páginas relacionadas