¿Qué estrategias usas para escribir comentarios?

Antes de empezar quiero dejar claro que no soy ningún experto a la hora de escribir comentarios en el código, pero tengo experiencia en programación, por lo que espero poder explicarte todo utilizando un lenguaje sencillo y sobre todo correctamente, aún así agradecería mucho que si detectas algún error a lo largo de este artículo, me lo comentes e intentaré solucionarlo con la mayor brevedad posible 🙂

Antes de que entremos en materia, os dejo la siguiente cita:

“Don’t comment bad code – rewrite it”
Brian W. Kernighan y P. J. Plaugher – The Elements of Programming style, 1978

Cuando terminamos de escribir una clase y vemos que no es fácil de entender, decidimos que la mejor manera de ayudar a los demás a conocer lo que hemos hecho es agregando comentarios. Debemos tener en cuenta que el código claro y expresivo es mil veces mejor que un código complejo con muchos comentarios. En lugar de invertir nuestro tiempo escribiendo comentarios, deberíamos invertirlo en limpiar nuestro desorden.

¿Qué tipos de comentarios se deben evitar?

* Debemos evitar los comentarios redundantes, los que expresan lo que hace el código claramente.

public string Direccion { get; set; } //Propiedad Dirección
int t = 1; //Se asigna el valor 1 a la variable t
void CalcularSaldo() //Calcula el saldo
var usuario = new Usuario(); //Crea una nueva instancia
//Constructor por defecto
public Util(){}

* Obsoletos o desactualizados, son usados para despistar al pobre programador de turno que le toco darle mantenimiento a tu código:

//Solo ingresan si el valor es mayor a 20
if(valor > 100){}
///
/// Envia un correo
///Parametro correo ///Formato Html void Enviar(string correo)

* Mal redactados, demuestran tu nivel de ortografía

//Sy s mallor a 20 pazan
if(valor > 100){}

* Los que se ofrecen disculpas, porque no saben lo que han echo.

try
{
servicioCorreo.EnviarNotificacion();
}
catch(Exception ex){
//Este metodo a veces no funciona por eso esta dentro de un try-catch
//para evitar que arroje un error
}

* Código comentado (Zombie Code), el que nunca quiere desaparecer y es considerado como un backup:

//servicioCorreo.EnviarNotificacion();
//servicioCorreo.EnviarNotificacionAdministrador();
//servicioCorreo.EnviarNotificacionSecretaria();
servicioCorreo.EnviarNotificacionEnCadena();

* Cierran llaves, para asegurarse que todos sepan dónde termina cada bloque de código:

try
{}
catch
{}//try-catch

while(true)
{}//while

if(true)
{}//if

2. Entonces, ¿Qué tipos de comentarios debo usar?

* Los que agregan información adicional:

//formato esperado kk:mm:ss EEE, MMMM, dd, yyyy
var timeMatcher = Pattern.Compile("\\d*:\\d*:\\d*\\w*,\\w*\\d*,\\d*");

* Indican la toma de una decisión:

//Se utiliza el objeto StringBuilder en lugar del string
//porque tiene mejor rendimiento
//Referencia: http://support.microsoft.com/kb/306822
var builder = new StringBuilder();
foreach(var mensaje in listaMensajes)
{
builder.Append(mensaje);
}

* Resaltan la importancia de una decisión:

//Es importante eliminar los espacios en blanco debido a que el servicio
//no los reconoce como caracteres validos
numeroCuenta = numeroCuenta.Trim();
AumentarLineaCredito(numeroCuenta);

Conclusión final

Ahora que ya sabes como comentar tu código, ahora sólo te queda ponerte manos a la obra.

Espero que os sirva! ¡Hasta otra! 🙂

Referencias: http://code2read.com/

Anuncios

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s