Los comentarios de código, se puede decir, son más importantes que el propio código. Aquí tienes algunos métodos para asegurarte de que los comentarios que escribes en el código sean amigables:
No repitas lo que el lector ya sabe.
Los comentarios que explican claramente lo que hace el código no nos ayudan.
// If the color is red, turn it green
if (color.is_red()) {
color.turn_green();
}
Comenta para explicar el razonamiento y el historial.
Si la lógica de negocio del código puede necesitar actualizarse o modificarse más adelante, deberías dejar un comentario.
/* The API currently returns an array of items
even though that will change in an upcoming ticket.
Therefore, be sure to change the loop style here so that
we properly iterate over an object */
var api_result = {items: ["one", "two"]},
items = api_result.items,
num_items = items.length;
for(var x = 0; x < num_items; x++) {
...
}
No escribas comentarios muy largos en la misma línea.
Nada enfurece más a los desarrolladores que arrastrar la barra de desplazamiento horizontal para leer un comentario. De hecho, la mayoría de los desarrolladores ignoran este tipo de comentarios porque leerlos es realmente incómodo.
function Person(name) {
this.name = name;
this.first_name = name.split(" ")[0]; // This is just a shot in the dark here. If we can extract the first name, let's do it
}
Pon los comentarios largos encima de la lógica y los cortos después.
Si el comentario no supera los 120 caracteres, puede colocarse junto al código. De lo contrario, deberías ponerlo directamente encima de la sentencia.
if (person.age < 21) {
person.can_drink = false; // 21 drinking age
/* Fees are given to those under 25, but only in
some states. */
person.has_car_rental_fee = function(state) {
if (state === "MI") {
return true;
}
};
}
No agregues comentarios innecesarios solo por comentar.
Los comentarios superfluos causan confusión. Quizás en la escuela te enseñaron a añadir comentarios a todas las sentencias para ayudar a los desarrolladores a entender mejor. Pero eso es un error. Si alguien dice eso, dale dos buenas bofetadas. El código debe mantenerse limpio y conciso, eso es indiscutible. Si tu código necesita explicaciones línea por línea, lo que más necesitas es refactorizarlo.
if (person.age >= 21) {
person.can_drink = true; // A person can drink at 21
person.can_smoke = true; // A person can smoke at 18
person.can_wed = true; // A person can get married at 18
person.can_see_all_movies = true; // A person can see all movies at 17
//I hate babies and children and all things pure because I comment too much
}
Escribe los comentarios con la ortografía correcta.
No pongas excusas por los errores ortográficos en los comentarios del código. El IDE puede revisar la ortografía por ti. Si no tiene esa función, descarga un plugin y ¡hazlo tú mismo!
Practica mucho.
La práctica hace al maestro. Intenta escribir comentarios útiles y pregunta a otros desarrolladores si tus comentarios son útiles. Con el tiempo, aprenderás gradualmente qué es un comentario amigable.
Revisa los comentarios de los demás.
En la revisión de código, a menudo tendemos a ignorar los comentarios. No tengas miedo de pedir más comentarios; deberías cuestionarlo. Si todos adquieren el buen hábito de escribir buenos comentarios, el mundo será un lugar mejor.
Resumen
Los comentarios son una parte muy importante del proceso de desarrollo, pero no deberíamos comentar solo por comentar. Los comentarios deben ser útiles, concisos y deben ser un complemento al código. No deben usarse para explicar el código línea por línea; al contrario, deben usarse para explicar la lógica de negocio, el razonamiento y las implicaciones futuras.