Los comentarios son, de cierta manera, un tema controvertido.
Hay dos opiniones muy fuertes en el desarrollo de software, ambas extremadamente populares y extendidas. La primera establece que los comentarios son malvados, y no deberías usarlos bajo ninguna circunstancia. El argumento principal es que en lugar de usar comentarios, deberías tratar de hacer el código tan legible como sea posible. Si el código está escrito de manera expresiva usando las mejores prácticas, los comentarios no son necesarios.
El segundo grupo piensa que los comentarios son una necesidad. El código no puede contener toda la información necesaria para mantener apropiadamente una solución, y los comentarios son una forma efectiva de comunicación para otros desarrolladores. Si todo lo que necesitáramos fuera el código, podríamos tomar los binarios y trabajar desde ellos.
Creo que ambos grupos tienen algo valioso que enseñar. Es cierto que los comentarios pueden ser peligrosos, algunas de las razones por las que podrías desconfiar de ellos son:
- Los comentarios fácilmente se vuelven obsoletos, y es poco razonable esperar que todos actualicen cada comentario cuando el código cambia. Sería algo ideal, pero rara vez sucede en la realidad.
- El código es la única fuente de verdad que se garantiza que sea cierta en cualquier punto dado a través del ciclo de vida del software.
- Un mal comentario es peor que no tener comentarios en absoluto, ya que te lleva a suposiciones erróneas.
- Cuando se usan en exceso, los comentarios saturan nuestro código y hacen más difícil encontrar las cosas que estamos buscando.
Los comentarios están esencialmente ahí porque no pudimos expresar perfectamente nuestras ideas en código. Cada vez que escribes un comentario, piensa si es posible refactorizar tu código de una manera que lo haga obvio para el lector. Con esfuerzo y experiencia, puedes remover la mayoría de los comentarios innecesarios de tus proyectos.
A pesar de sus desventajas, los comentarios pueden ser usados para comunicarse efectivamente con otros desarrolladores. El truco es no repetir tu código, sino clarificar su intención y proveer información extra valiosa que no puedes representar en código. Si puedes mantener tus comentarios a un nivel más alto de abstracción, tendrás una herramienta poderosa para hacer tu código más mantenible.
Echemos un vistazo a 5 escenarios donde usar comentarios puede ayudar a mejorar la legibilidad de nuestro código:
Explicando la intención y respondiendo por qué
Explicar por qué las cosas se hacen de una manera específica en el código es uno de los usos más aceptados para los comentarios.
La razón es simple: el código mismo solo te dice qué está ahí, no por qué está ahí. Las motivaciones detrás de decisiones aparentemente arbitrarias en diseño y desarrollo usualmente se encuentran en la documentación, pero si necesitas mantener esta información en el código fuente, los comentarios son la mejor forma de hacerlo.
Siéntete libre de agregar comentarios si sientes que algo se ve muy arbitrario, o para dejar que otros desarrolladores sepan por qué estás haciendo las cosas de la manera que las estás haciendo. No escribas un ensayo enorme apoyando la decisión, una línea rápida es suficiente para transmitir información. Otros desarrolladores apreciarán esta información valiosa.
Clarificando detalles
A veces necesitas escribir pequeñas aclaraciones para argumentos de entrada o datos devueltos de una función, en este caso, un comentario podría hacer las cosas más fáciles de entender.
También es útil para resumir una serie de operaciones complicadas: escribir un pequeño comentario que explique la intención de las siguientes líneas es útil para entender cómo trabajan juntas.
Otro uso común es especificar las unidades de una variable: ¿esto se supone que sea una distancia en metros o pies?
Este podría ser el caso de uso más débil de la lista porque los comentarios de este tipo se vuelven inútiles al darle a las variables y funciones buenos nombres. Si quieres algunas guías para nombrar variables, puedes leer el artículo anterior sobre el tema.
Advirtiendo al usuario de un método sobre efectos secundarios
Hay métodos con efectos secundarios ‘peligrosos’. Algunos de ellos realizarán acciones que son difíciles o imposibles de revertir o removerán registros de un registro importante.
Podrías tener en su lugar algunas convenciones de nomenclatura especiales para hacer esto claro. La comunidad Ruby, por ejemplo, tiene una convención para agregar un carácter ‘!’ al final de métodos que realizan este tipo de acción. Si hay necesidad de una explicación más detallada, siéntete libre de agregar un comentario explicando los posibles peligros de llamar a un método específico.
# ¡Advertencia!: Este método detendrá el pipeline y todos los datos no procesados se perderán,
# asegúrate de que la cola esté vacía antes de llamarlo, de otra forma, podrías perder datos.
def perform_teardown():
# Implementación de este método
return
Comentarios TODO
Puedes agregar pequeños recordatorios para cosas que necesitas mejorar o refactorizar después. Hay muchos cambios que no merecen un nuevo ticket en el sistema de seguimiento de issues, y esos pequeños recordatorios pueden ser útiles para no olvidar estas pequeñas mejoras.
La mayoría de editores de texto modernos e IDEs tienen herramientas para encontrar esos TODOs, y tengo la característica habilitada en cada uno que uso (de hecho, es una de las primeras cosas que hago cuando configuro un nuevo sistema). Úsalos con confianza, los comentarios TODO están bien.
# TODO: Averiguar si hay una alternativa eficiente para álgebra lineal y hacer este método un wrapper alrededor de ella
def transpose_matrix(matrix)
# código para transponer una matriz
end
Documentación de API pública
Documentar la interfaz pública de tus clases es una parte muy importante del desarrollo de software. Quieres que otros usuarios (y bueno, tú también) sepan cómo usar tus clases y código. Hay muchas herramientas que te permiten convertir comentarios en documentación (PDF, HTML, y otros formatos), siempre que escribas tus comentarios con un formato específico. La herramienta escaneará tu código y extraerá toda la información requerida para los documentos.
Algunos ejemplos populares son Javadoc para Java y YARD para Ruby, los comentarios encima de los métodos se ven así:
Javadoc:
/**
* <p>Traduce texto del inglés a lenguaje alienígena
* </p>
* @param textInEnglish el texto en inglés que quiero traducir
* @return el texto después de ser traducido a lenguaje alienígena
*/
public String translateToAlienspeak(String textInEnglish) {
// contenidos de la función
}
YARD:
# Traduce un texto del inglés a lenguaje alienígena
#
# @param text_in_english [String] el texto en inglés que quiero traducir
# @return [String] el texto después de ser traducido a lenguaje alienígena
def translate_to_alienspeak(text_in_english)
# contenido de la función
end
No todos los comentarios son comentarios geniales, pero algunos sí lo son
Estos son solo un par de casos donde los comentarios son útiles, pero hay muchos otros escenarios donde usar un comentario es lo correcto.
El truco para escribir buenos comentarios es preguntarte por qué los estás escribiendo en primer lugar. ¿Es para arreglar una deficiencia en la claridad de tu código? Si ese es el caso, detente y refactoriza tu código para hacerlo más legible. Como dijimos antes, la mayoría de los comentarios pueden ser omitidos en favor de un pedazo de código mejor escrito.
Por otro lado, si estás dando información que tus colegas encontrarán útil, y no hay forma de embebir esa información en el código, entonces ve por un comentario. Los buenos comentarios pueden ser extremadamente útiles. Solo asegúrate de que sean comentarios buenos, no parches perezosos para código que aún puede mejorar.
En el próximo artículo, veremos escenarios donde los comentarios son definitivamente una mala elección.
Qué hacer a continuación:
- Comparte este artículo con amigos y colegas. Gracias por ayudarme a llegar a personas que podrían encontrar útil esta información.
- Puedes encontrar más información sobre crear buenos argumentos de función en el capítulo 4 de Clean Code.
- Envíame un email con preguntas, comentarios o sugerencias (está en la página Autor).