En la mayoría de los casos los comentarios en el código son code-smells. No porque lo comentarios sean malos, solamente porque no lo usamos correctamente. Veamos algunos ejemplos de comentarios mal usados.
// Returns list of Products.
public List<Product> GetProducts(int barCode)
{
}
Vemos que el método se llama GetProducts(). Es bastante obvio que el método devolverá una lista de Product. El comentario dice que devolverá una lista de Products. ¿Tiene algún valor este comentario? No, verdaderamente con solo un golpe de vista sobre el método sabremos qué hacer. El comentario esta demas.
// Create new connection to the database var connection = new SqlConnection();
En este estamos creando una nueva conexión a base de datos. También, es bastante obvio lo que estamos intentando hacer. Nuevamente, el comentario esta demas.
// If the number stock is less than 5, notify
// the product. Otherwise, issue a fine.
if(stockToday < 100)
NotifySuppliers();
else
IssueFine();
Primero veamos el código y leamos, seria algo asi como, si stockToday es menos ejecutar NotifySuppliers, si no, IssueFine(). Con solo leer el codigo sabemos lo que hace. El comentario dice exactamente lo mismo. No tiene sentido. El comentario solo indica lo obvio.
Otro problema que podemos tener con este tipo de comentarios es que si alguien cambia la implementación seguramente no cambiará el comentario dejándolo obsoleto. Esto lo haría muy confuso para el siguiente programador que tome este código.
Por esto tengamos en cuenta algo muy importante. Si el código es suficientemente descriptivo y autoexplicativo no será necesario comentarios.
//Version v1.9
if(isActive){}
Comentarios que versionan un historial. Este es bastante frecuente entre los programadores. Algunos ponen el nombre del autor, que versión, que se cambio, etc. Imaginemos si tenemos todo el historial de cambios comentados de un proyecto de 5 años.
// 10 Ene 2019 - Fernando Sonego: ... // 4 Feb 2019 - Homero Simpsons: ... // 28 Feb 2019 - Armando Barreda: ... //... //... //... //... //... public class WorkOrders
La persona que tome último este código ¿Leerá todos los comentarios? seguramente no. Este tipo de comentarios son poco útiles. Si necesitamos versionar nuestro código dejemoslo a herramientas de versionado como Git.
private int _tf; // total days
Comentarios para aclarar variables. Innecesario. Como comentamos anteriormente, si nuestro código es bastante descriptivo no necesitamos los comentarios. La solución es que la variable se llame directamente TotalDays.
// public class WorkOrders
// {
// }
Código Muerto. Muchos dejan un código comentario que cambiaron ¿Porque? la respuesta que recibo siempre es “por las dudas si lo vuelvo a necesitar”. Si no usamos debemos borrarlo y si en algún momento lo necesitamos podemos consultar en nuestro controlador de código fuente.
///<summary>
/// Returns list of products
///</summary>
///<param name="barCode"></param>
///<returns></returns>
public List<Product> GetProducts(int barCode)
{
}
Summary es un caso especial. Tal vez puede ser necesario, si estamos usando alguna herramienta automática de documentación por ejemplo. La mayoría de las veces es utilizado para el desarrollo de framework para proveer información sobre las clases y métodos públicos. Pero si no estamos trabajando en un framework no son necesarios.
public List<Product> GetProducts(int barCode)
{
//TODO: We need to get rid of abcd once we revisit this method. Currently, it's
// creating a coupling betwen x and y and because of that we're not able to do
// xyz.
throw new NotImplementedException();
}
TODO comments, otro caso especial. Nos indica que estamos trabajando en algún código y que tal vez tenga algún problema. Es un buen comentario. Podemos escribir este tipo de comentario, como marcador, y poder seguir con nuestro código. Luego, al finalizar, volver a solucionarlo. Este podemos encontrarlo en una vista especial que tiene el Visual Studio llamada Task List.
Este tipo de comentarios está perfecto. Recordemos, este tipo de comentarios es bueno para marcar si debemos en algún momento volver a él para repararlo en algún problema.
public void SubmitOrder(Order order)
{
// Save order to the database
_dbContext.Orders.Add(order);
_dbContext.SaveChanges();
// Send an email to the supplier
var client = new SmtpClient();
var message = new MailMessage("info@info.com", order.Customer.Email, "New order was successfully placed.", ".");
client.Send(message);
}
Aca vemos 2 comentarios que hacen 2 cosas distintas. Si tenemos estos comentarios que hacen referencia a más de una linea de codigo, seguramente, debemos refactorizarlos a 2 métodos independientes. Estamos usando comentarios para agrupar código que tranquilamente puede ser un método.
public void SubmitOrder(Order order)
{
SaveOrder();
NotifySupplier();
}
private void SaveOrder()
{
_dbContext.Orders.Add(order);
_dbContext.SaveChanges();
}
private void NotifySupplier(WorkOrders order)
{
var client = new SmtpClient();
var message = new MailMessage("info@info.com", order.Customer.Email, "New order was successfully placed.", ".");
client.Send(message);
}
Más limpio, más claro, más descriptivo. Recordemos, nuestro código tiene que contar una historia.
Conclusión
No debemos olvidar que si tenemos métodos con 50 líneas de código se hacen difícil de leer y es una buena práctica extraer el código en varios métodos.
Para resumir, tratemos de no escribir comentarios, reescribimos nuestro código para hacerlo más descriptivo. No expliquemos ”Que” es muy obvio si el código esta bien descrito. Solamente expliquemos Por Qué y Cómo.
