Comments - ajpaez/Learning GitHub Wiki

Recuerda: El uso correcto de los comentarios es para compensar por nuestros propios fallos al expresarnos en nuestro código

• Los comentarios no compensan el mal código. La mayor motivación para escribir comentarios es el código malo. Antes de pensar en que debes de comentar alguna parte de tu código porque no la entiendes, piensa primero en refactorizarla Código limpio y expresivo con pocos comentarios está por encima del código desordenado y complejo con millones de comentarios No inviertas tiempo escribiendo comentarios que expliquen tu desorden, inviértelo en ordenarlo.
• Explícate con el código. Solo necesitas unos pocos segundos para explicar con código lo que intentas hacer. En muchos casos es simplemente crear una función que siga lo mismo que el comentario que quieres escribir.

Algunos comentarios son necesarios o beneficiosos, pero tenga en mente, el único comentario verdaderamente bueno es aquel que encuentras la forma de no escribir.

• Explicando la intención. Algunas veces un comentario va más allá de la información útil sobre la implementación y nos da la intención que hubo detrás de la decisión tomada.
• Clarificadores y/o amplificadores. Algunas veces es bueno traducir el significado de algún argumento o valor retornado en algo entendible o si queremos ampliar la importancia de algo que pueda parecer intranscendente.
• Advirtiendo sobre las consecuencias. Algunas veces es bueno dejar un advertencia sobre nuestra experiencia con alguna parte del código o función/rutina usada
• Comentarios TODO

La mayoría de nuestros comentarios caerán en esta sección. Generalmente ellos soportaran o excusaran a un código pobre o las decisiones tomadas por decisiones insuficientes.

• Comentarios oscuros. Estos son esos comentarios que dejas en el código por que sientes que debes de hacerlo o porque el proceso lo requiere. Si decides escribir un comentarios, entonces invierte el tiempo necesario para hacerlo con seguridad, entonces, este será un buen comentario. Cualquier comentario que nos obligue a mirar en otras partes del código para buscar el sentido de ese comentario, has fallado al comunicarte y no tiene ningún sentido.
• Comentarios redundante.
• Comentarios confusos.
• Comentarios requeridos. No establezcas normas obligatorias para dejar comentarios, como javadoc en cada función o un comentario para cada variable.
• Comentarios diario.
• Comentarios ruidosos. Son esos comentarios que ves pero no están haciendo nada menos ruido, reafirman lo obvio y no ofrecen información nueva.
• No uses comentarios cuando puedas usar una función o variable. Son aquello comentarios que se "complementan con código" y eso no es lo que buscamos, el comentario debe de complementar al código. Comprueba si con un refactor de código, creando una función con un buen nombre y algunas variables ese comentario desaparece.
• Marcadores de posición. Piénsalo de esta forma, estos banners no tiene sentido ni obviedad si tu no ves banners muy a menudo. Úsalos con mucha moderación y solo cuando su beneficio sea signifícateme. Si sobre abusas de ellos, entonces caerán en ruido de fondo y serán ignorados.
• Comentarios de cierre de bloque. aquellos que marcan el final de un if } //if o un try } //try no son necesarios con los IDE's actuales.
• Código comentado. Pocas prácticas son tan odiosas como comentar código, No lo hagas!! Solo puede llevar a confusión para quien lee tu código