Clean Code #10: Comentarios

Comentarios

En la mayoría de los casos los comentarios en el código son code-smells. No porque los comentarios sean malos, solamente porque no lo usamos correctamente. Veamos algunos ejemplos de comentarios mal usados.

// Returns list of customers in a country.
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 está demás.

// 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 está demás.

// 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, sería algo así como, si stockToday es menos ejecutar NotifySuppliers, si no, IssueFine(). Con solo leer el código 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 auto explicativo no serán necesarios 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 cambió, 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 este código ¿Leerá todos los comentarios? seguramente no. Este tipo de comentarios son poco útiles. Si necesitamos versionar nuestro código dejémoslo 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 ¿Por qué? 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 utilizada 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 son perfectos. 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);

}

Acá vemos 2 comentarios que hacen 2 cosas distintas. Si tenemos estos comentarios que hacen referencia a más de una línea de código, seguramente, debemos factorizarlos 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 codigo esta bien descripto. Solamente expliquemos Por Qué y Cómo.