Por qué es importante comentar el código
22/11/2017 por alvar0hurtad0

Front.id

Lo reconozco, soy un maníatico del código. Me pongo nervioso cuando una llave no está donde el estándar de código dice que debe estar, cuando se usa camel-case donde no se debe y cuando alguien mete código comentado en un commit.

Otra de mis manías es la documentación interna, creo que en muchas ocasiones marca la diferencia entre un buen desarrollador y un desarrollador excelente. A continuación os explico por qué:

Documentar los encabezados de nuestras funciones y métodos es necesario para que nuestro IDE nos eche una mano con el tipado y sentido de los argumentos que pasamos.

Seguramente muchos habréis visto lo útil que es que cuando estás usando un método o función que el IDE te diga si espera un array, un string o un objeto de la clase XXX.

 

Proporcionando el tipo de los parámetros

 

Pues esta magia es posible gracias a la documentación del encabezado del método en cuestión:

 

createInstace interface definition

Documentar los tipos de las variables y las propiedades hace que sepamos qué podemos hacer con ellos y recivamos avisos de asignaciones incorrectas.

Otra función muy útil de nuestros IDEs es sugerir métodos cuando usamos variables. Es especialmente útil en lenguajes como PHP o Javascript cuyo tipado es débil:

Sugerencia de métodos

Esto es gracias a documentar los tipos  dentro del namespace cuando declaramos la propiedad:

Definición de método.

Los comentarios internos del código nos ayudan a que se entienda lo que queremos hacer, pero también a alcanzar mejores soluciones.

Además de lo evidente, de que hay que explicar lo que hacemos en el código para que otros (o nosotros mismos en el futuro) puedan entenderlo. Hay un aspecto importante sobre explicar lo que estamos haciendo.

Seguramente muchos utilicemos a menudo la técnica del patito de goma para encontrar soluciones a nuestros problemas. Pues documentar aveces tiene el mismo efecto. Esforzarnos en explicar nuestro código mediante comentarios pone en evidencia cuando estamos haciendo mal o cuando estamos dando rodeos innecesarios.

Por otro lado, el momento de poner comentarios a lo que hacemos, ya sea antes o después de escribir el código es el momento en el que algunos reflexionamos sobre la solución que hemos elegido, por lo que cuando vemos un código sin ningún comentario lo primero que pensamos es que la persona que lo ha escrito, probablemente, no se lo ha pensado dos veces cuando ha implementado su solución.

Agregar nuevo comentario

El contenido de este campo se mantiene privado y no se mostrará públicamente.

HTML Restringido

  • Etiquetas HTML permitidas: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • Las líneas y los párrafos se rompen automáticamente.
  • Las direcciones de las páginas web y las direcciones de correo electrónico se convierten en enlaces automáticamente.