Pero no se desarrollaron de ninguna manera. Desde los primeros lenguajes de programación hasta el día de hoy, los comentarios sobre el código son solo texto estático (con algunas excepciones, que analizaré).
Bueno, ¿qué más puedes mejorar o inventar? Reflexionemos sobre este tema: ¿es posible mejorar de alguna manera nuestra experiencia de interactuar con un aspecto tan importante pero tan ignorado de la programación como la documentación en código o en un simple comentario?
Para empezar, se dedicarán un par de párrafos al tema del título de este artículo. Sí, porque realmente no existe esta historia de desarrollo, por lo que puede llamar al título provocativo. Un pequeño descargo de responsabilidad: mi conocimiento es limitado (descendiendo en experiencia) a estos lenguajes: amplia experiencia: TS, JS, Rust, medio: PHP, C ++, pequeño: Go, Java.
Entonces, todo lo que tenemos es esto: un JSDoc abandonado y con errores, finalmente muerto en la era de TypeScript, por cierto, para el cual no hay menos TSDoc con errores y abandonados. Para PHP, hay PHPDoc, que fue poco útil cuando codifico en este lenguaje. Confieso que tengo la experiencia más pequeña en C ++, por lo que no he oído hablar de nada parecido, y CppDoc encontrado en Google no causa nada más que una sonrisa triste. El más desarrollado en este sentido es Rust, como siempre. Tiene un excelente sistema RustDoc, pero desafortunadamente no siempre es ergonómico y el IDE aún no lo admite.
Por lo tanto, la imagen general es bastante triste, y la infraestructura de comentarios en torno al código no ha cambiado desde el comienzo del historial de programación. Los comentarios se ven igual que hace 90 años en el Plancalcule condicional, como en el código de ensamblador de la computadora del módulo lunar Apollo 11.
(foto de shopify.com)La historia ha terminado. Ahora, ¿qué tiene de malo el hecho de que los comentarios son solo texto estático? ¿No es perfecto el texto estático y se puede mejorar algo? Inventaron algunos hipertextos y HTML, Internet lo rodea. ¿Pero quién necesita todo esto? ¿Qué es tan difícil de escribir manualmente en las URL? Los millennials eran bastante vagos.
Por supuesto que fue sarcasmo. Pero, ¿qué tiene que ver el hipertexto con los comentarios sobre el código? Pensemos qué problemas resolvió el hipertexto y ¿hay algún problema similar al usar comentarios de código?
Entonces, el hipertexto convirtió el texto estático en texto con hipervínculos. La forma más fácil de comprender los beneficios de esto es leyendo el artículo de Wikipedia. Por ejemplo, sobre el
Gran Colisionador de Hadrones . Después de comenzar a leer el artículo, la mayoría de las personas entenderán qué son los protones y los iones si no se pierden las lecciones de física. Pero entonces aparece la palabra "Hadron". ¿Qué es y cómo puede averiguarlo el lector? Si se tratara de un texto estático, no habría muchas opciones, excepto encontrar en algún lugar (¿en la biblioteca?) Otro texto donde diga qué es Hadron. Pero gracias a Dios esto no es así, y podemos hacer clic en el hipervínculo.
Pensemos, ¿existen tales situaciones en la programación? Miles de ellos Para encontrar un ejemplo, vaya a casi
cualquier repositorio abierto, como el kernel de Linux. Entré en el primer
archivo que obtuve
static void irq_cpu_rmap_notify() { }
Entonces, imagine que recientemente se unió al proyecto y de repente algo se rompió. Backtrack conduce a esta función, pero no sabes nada al respecto. Que deberias hacer Así es: use todo lo que tiene para comprender de qué se trata esta función: el código en sí y los comentarios al respecto. El texto humano es generalmente más fácil de entender que el código en sí, ¿verdad? Por lo tanto, comenzamos leyendo el comentario. Y luego nuestro estado de ánimo cae por debajo del zócalo.
¿Qué tipo de IRQ? No tienes idea de lo que es. ¿Cuáles son los próximos pasos? ¿Contactar y distraer a colegas más experimentados? Puede, por supuesto, pero no quiere realmente. ¿O están de vacaciones? Buscar por código? Encontrará miles de referencias a esta abreviatura, y esto lo deprimirá. Bueno, digamos que buscaste la mitad de la base del código y aparentemente encuentras una explicación de lo que significa esta IRQ. Pero también sucede que esta explicación es otra sigla IRQ, ¡que tiene un significado completamente diferente! Bueno, el último caso es bastante raro, pero aún así.
Pero, ¿qué sucede si hace clic en la palabra IRQ y milagrosamente, su IDE lo llevaría al lugar de definición de esta abreviatura? Eso sería genial, ¿verdad? Y además, simplemente, no es más complicado que el hipertexto.
Entonces, ¿por qué en 2020 los programadores mismos no harán una herramienta así? Destacaría tanto la cápsula como la negrita oración anterior. La razón de esto es un gran misterio para mí. Quizás haya otros para IDEs, pero no encontré nada para VSCode. Por lo tanto, hice
esta extensión yo mismo. Te invito a probar y expresar tu opinión.
Pero continuemos.
Al leer el fragmento de código anterior, o más bien un comentario, surgen preguntas en casi todas las palabras. Por ejemplo, ¿dónde se encuentra esta estructura irq_affinity_notify? ¿O por qué en 2020 no puedo hacer clic en irq / manage.c para que el IDE me transfiera de manera diligente y rápida a este archivo? Esto también es un gran misterio para mí. Por lo tanto, en mi extensión, el primero ya se ha resuelto, pero hasta ahora solo para JavaScript y TypeScript (lo siguiente: C / C ++, Rust, Java, Go), y el segundo como menos significativo también se resolverá, pero un poco más tarde.
No quiero aburrirte más con un montón de texto, así que solo inserta un gif con un par de ejemplos más de trabajo:
Tengo mucho miedo a las críticas y los comentarios tóxicos, pero quiero saber aún más qué piensa sobre esto.