5 Comentarios útiles

Uno de los principios básicos de los desarrolladores de Software es:

“Todas las funciones deben ser documentadas”.

Habrá quien esté de acuerdo con esto y habrá quienes no, tu ¿Estas de acuerdo?, tu, ¿Documentas tus funciones?. Pues este principio es algo polémico ya que hay quienes dicen que:

“La mayoría de los comentario son una forma de duplicación…”

¿Por qué se dice esto?

En la siguiente imagen, se puede observar cómo la documentacion se duplica con el comentario de la función que se codificó:

¿Cómo hacer comentarios útiles y evitar la duplicación?:

Para evitar la duplicación y generar comentarios útiles debemos responder a las preguntas que se muestra en la siguiente imagen.

Who: ¿Quién hizo este código? el comando git blame nos dice qué persona hizo el código.

What: ¿Qué hace esta función? o esta clase? Esto nos lo debe decir el nombre de la función.

Where: El IDE nos dice en qué lugar es utilizada la función.

Why: El porqué o para qué sirve la función, es lo que se pone en el comentario.

How: El código dice como lo hace.

Estas preguntas nos ayudan a realizar comentarios útiles, sobre todo si se comienza a documentar el código y no se sabe como comenzar.