Repensar los comentarios del código

Justin Duke pregunta si tratar los comentarios de código como notas a pie de página podría ayudarnos a comprender mejor el código de un archivo. En su maqueta, todos los comentarios están ocultos de forma predeterminada y requieren un clic para revelarse:

¡Qué buena idea! El diseño de Justin me recuerda la forma en que Instapaper trataba las notas a pie de página en línea.

Supongo que la razón por la que me gusta tanto esta idea es que no es necesario leer muchos comentarios constantemente; son una especie de recordatorio de que “Oye, esto necesita mejorarse en el futuro” o “Ay, esto Es raro y lo siento”. Mantener estos comentarios fuera del código también hace que sea mucho más fácil escanear todo el archivo.

Me pregunto si podría haber una opción que muestre cada comentario, en caso de que necesite leer todos los comentarios en secuencia en lugar de hacer clic para alternar cada uno.

De todos modos, toda esta charla sobre comentarios me recuerda una charla absolutamente fantástica de Sarah Drasner en JSConf este año donde habló de por qué es tan difícil hacer los comentarios correctamente: