capitulo 6 the art of readable code

1. Making Comments
Precise and Compact
Octavio Vélez G.
Gestión de la calidad del software

2. Keep Comments Compact
Forma no ideal:
No es necesario usar 3 líneas para
explicarlo, por el contrario, lo
podemos hacer de la siguiente
manera:

3. Avoid Ambiguous Pronouns
Se necesita un trabajo extra para que el lector pueda entender a que se
refiere un pronombre. Y en algunos casos, no está claro. Por ejemplo:
Si por ejemplo, me quiero referir a los datos, una forma de dejarlo claro es de
la siguiente manera:
También es posible reestructurar la frase para lograr ser precisos con lo que
se quiere expresar.

4. Describe Function Behavior Precisely
Imagine que acaba de escribir una función que cuenta el número de líneas en
un archivo:
Este comentario no es muy preciso ya que hay muchas maneras de definir
una "línea".

5. Describe Function Behavior Precisely
Si en este caso la implementación consistiera en contar el número de
caracteres de nuevas líneas (n). El comentario adecuado sería:
Este comentario no es tan largo en comparación a la primera versión pero si
contiene mucha más información para el lector del código. De manera que le
permite entender fácilmente que hace la función.

6. Use Input/Output Examples That Illustrate Corner
Cases
Un comentario con un ejemplo de entrada / salida bien elegido puede valer
más que mil palabras.
Por ejemplo para una función que remueve partes de una cadena.
Este comentario no es muy preciso ya que el lector no sabría con claridad
como opera dicha función y podrían surgir ciertas preguntas.

7. Use Input/Output Examples That Illustrate Corner
Cases
Un ejemplo bien elegido, daría claridad a su funcionalidad.
Mientras que un ejemplo muy sencillo, sería igual de ambiguo que la
definición inicial.

8. State the Intent of Your Code
Comentar es decirle al lector en qué se pensaba cuando se escribió el código.
Desafortunadamente, muchos comentarios terminan simplemente
describiendo lo que hace el código en términos literales, sin agregar nueva
información.
La ventaja que tiene un comentario que describa que se pretendía hacer con
el código, es que permite al lector verificar si lo descrito en el comentario es
lo que realmente hace la función. Es decir, el comentario ayuda como una
comprobación extra de que el código esté bien desarrollado.

9. Conclusiones.
• Describir el comportamiento de una función con tanta precisión como sea
práctico.
• Ilustre sus comentarios con ejemplos de entrada / salida cuidadosamente
seleccionados.
• Indique la intención de su código a grandes rasgos, en lugar de los detalles
obvios.
• Mantenga sus comentarios breves usando palabras que tienen mucho
significado.