Cómo escribir buenos comentarios de código: "por qué", no "cómo"

¡Hola, Habr! Les presento la traducción del artículo "Escribir buenos comentarios: el por qué, no el cómo" de Jack Franklin.







Comentar el código en un entorno de programación a menudo se considera una pérdida de tiempo o una señal de que el código se puede mejorar. Aquí hay una cita del archivo CONTRIBUTING.md que encontré en GitHub (y hay muchos ejemplos de este tipo):

Deben evitarse los comentarios. Si su código no se puede entender sin comentarios, vuelva a escribirlo para que se explique.

Creo que en la mayoría de los casos, estos consejos no tendrán éxito y serán incorrectos. Este enfoque, creo, tiene sus raíces en las experiencias de aprendizaje de la mayoría de las personas que han estudiado programación. Cuando estudié informática en la universidad (aunque este consejo se puede encontrar en muchos cursos, no necesariamente universitarios), recuerdo mucho en el primer semestre a un profesor que dijo:

Cada línea de código debe tener un comentario que explique lo que hace. Su trabajo en el curso se juzgará según este criterio.

Entonces, digamos que es un estudiante recién horneado que recién comienza este curso. ¿Qué vas a hacer? ¡Comenta el código, por supuesto!

//      bar
const inputValue = process.ENV.bar

//     2
const newValue = inputValue * 2

//     square
const finalValue = square(newValue)

//         
const square = (x) => x * x

Las personas que dicen que los comentarios son malos en realidad piensan en comentarios como este. ¡Y tienen toda la razón! Comentarios como los anteriores, respondiendo a la pregunta "¿cómo?" En programación, son completamente inútiles. Todos estos comentarios no agregaron nada al código que no se pueda entender desde el código mismo.

Responda la pregunta "¿por qué?"

El problema con los comentarios anteriores es que explican cómo . Explica los pasos que damos en el código. Estos comentarios rara vez son útiles; el código en sí es mucho mejor para decirte qué hacer. Después de todo, las líneas de código son solo instrucciones que le dicen a la computadora cómo completar una tarea.



Por lo general, no hay necesidad de una gran cantidad de comentarios, porque puede escribir código simple sin características o matices que le darían un aspecto incomprensible. Pero a veces surgen situaciones en las que es imposible escribir código elemental e intuitivo. Tal vez sea un error que tenga que solucionar. O heredó la felicidad de desarrolladores anteriores en forma de un sistema que no le permite resolver el problema de la manera que le gustaría. O, al final del día, simplemente no hay una manera fácil de mejorar su código.



Una vez trabajé en una empresa de procesamiento. Todos los días realizamos una gran consulta SQL que seleccionaba pagos a pagar. La consulta estaba bien optimizada (necesitábamos que fuera muy rápida) y extremadamente compleja, con muchos casos extremos a considerar. Nos esforzamos mucho para dejarlo lo más claro posible. Sin embargo, esta solicitud nunca podría ser completamente intuitiva y fácil de entender. Simplemente contenía demasiado código con un montón de condiciones y lógica que solo podían entenderse en el contexto de nuestra empresa y cómo funcionaba.



Quería encontrar un ejemplo para mostrar aquí, así que me adentré en el código base de React para encontrar algo. No necesitas ser un desarrollador de React para descubrirlo. Entonces, aquí está el código que me gustaría resaltar:

//  key     .    , 
//  key      (, <div {...props} key="Hi" />
//  <div key="Hi" {...props} /> ).     key,   ,
//      jsxDEV   , 
// <div {...props} key="Hi" />,       ,
//    key   . 
if (maybeKey !== undefined) {
  key = '' + maybeKey
}

( Y aquí hay un enlace en GitHub ).



Preste atención al código en sí:

if (maybeKey !== undefined) {
  key = '' + maybeKey
}

No es tan difícil averiguar qué hace. Si maybeKey no está especificado, asignamos el valor de maybeKey en cadena a key. Nota: Este es un pequeño truco de JavaScript para '' + maybeKeyconvertir el contenido de maybeKey en una cadena.



Pero aquí toda la pregunta es por qué . El comentario de este código es genial. Señala el problema, da dos ejemplos y también explica cómo solucionar este problema a largo plazo y qué estamos haciendo a corto plazo.



Si desea ver algún comentario que dejé en el código que escribí, aquí hay uno (TypeScript / Closure Compiler) . Este es un buen ejemplo del tipo de comentarios que encuentro muy valiosos.



Al final, se puede entender cualquier código. Después de todo, el código no es más que instrucciones que le dicen a la computadora cómo proceder. El código puede ser confuso, pero no puede mentir; si el tiempo es suficiente, cualquier desarrollador puede revisar el código paso a paso y comprender lo que está haciendo. A veces es mucho más difícil entender por qué lo hace. Así que deje a sus compañeros de trabajo (o futuro-usted mismo-dentro de seis meses) algo de contexto sobre por qué y para qué su código hace lo que hace. Será mucho mejor.