Anotar código fuente con diagramas como comentarios

Escribo mucho código (principalmente c ++ y javascript) que toca la geometría computacional y los gráficos y ese tipo de temas, por lo que descubrí que los diagramas visuales han sido una parte indispensable del proceso de resolución de problemas.

Ahora mismo he determinado que "oh, ¿no sería fantástico si de alguna manera pudiera adjuntar un diagrama dibujado a mano a un fragmento de código como comentario", y esto me permitiría volver a algo en lo que trabajé, días, semanas, meses antes y mucho más rápidamente vuelven a analizar mis algoritmos.

Como estudiante visual, siento que esto tiene el potencial de mejorar mi productividad con casi todos los tipos de programación porque los diagramas simples pueden ayudar a comprender y razonar sobre cualquier tipo de estructura de datos no trivial. Gráficos por ejemplo. Durante la clase de teoría de grafos en la universidad, solo había sido capaz de comprender realmente las relaciones de grafos de las que realmente podía dibujar representaciones esquemáticas.

Entonces...

Ningún IDE, que yo sepa, le permite guardar una imagen como un comentario en el código.

Pensé que yo u otra persona podríamos encontrar alguna herramienta razonablemente fácil de usar que pueda convertir una imagen en una cadena binaria base64 que luego pueda insertar en mi código.

Si el proceso de conversión / inserción se puede simplificar lo suficiente, permitiría una conexión mucho mejor entre el diagrama y el código real, por lo que ya no necesito buscar cronológicamente a través de mis cuadernos. Aún más impresionante: complementos para que los IDE analicen y muestren automáticamente la imagen. No hay absolutamente nada difícil sobre esto desde un punto de vista teórico.

Supongo que me tomaría un tiempo extra descubrir realmente cómo extender mis IDEs favoritos y mantener estos complementos, por lo que estaría totalmente contento con una especie de postprocesador de código que haría el mismo análisis y representación de las imágenes y mostrarlas junto con el código, dentro de un navegador o algo así. Como soy un programador de JavaScript de oficio.

¿Qué piensa la gente? ¿Alguien pagaría por esto? Me gustaría. Pero quizás también quisiera señalar que, independientemente de si yo o algún número significativo de mis pares pagaría por tal cosa, la única forma en que tal cosa podría tener éxito sería a través de un lanzamiento de código abierto.

¿Qué pasa con el complemento de inserción de imagen para Visual Studio ?

Si está utilizando un IDE diferente y no admite imágenes incrustadas o no tiene tiempo para extenderlo, entonces, ¿qué hay de poner un enlace a una imagen en los comentarios, mientras que la imagen residiría en algún lugar del repositorio? ?

Si no eres un artista ASCII , puedes usar doxygen como herramienta de documentación junto con dot / graphviz integrado en él.

Esto permite escribir descripciones textuales de gráficos y presentarlos en la documentación.

Por ejemplo, esta descripción:

digraph finite_state_machine {
    rankdir=LR;
    size="8,5"
    node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
    node [shape = circle];
    LR_0 -> LR_2 [ label = "SS(B)" ];
    LR_0 -> LR_1 [ label = "SS(S)" ];
    LR_1 -> LR_3 [ label = "S($end)" ];
    LR_2 -> LR_6 [ label = "SS(b)" ];
    LR_2 -> LR_5 [ label = "SS(a)" ];
    LR_2 -> LR_4 [ label = "S(A)" ];
    LR_5 -> LR_7 [ label = "S(b)" ];
    LR_5 -> LR_5 [ label = "S(a)" ];
    LR_6 -> LR_6 [ label = "S(b)" ];
    LR_6 -> LR_5 [ label = "S(a)" ];
    LR_7 -> LR_8 [ label = "S(b)" ];
    LR_7 -> LR_5 [ label = "S(a)" ];
    LR_8 -> LR_6 [ label = "S(b)" ];
    LR_8 -> LR_5 [ label = "S(a)" ];
}

se presenta como:

Puedes probar el modo artista de emacs. Haría arte ascii en lugar de imágenes per se, por lo que puede o no ser lo que estás buscando. En particular, si su IDE no hace fuentes de ancho fijo, no sería útil. Al ser texto sin formato, jugaría muy bien con el control de versiones.

Aquí hay un screencast del modo artista que se está utilizando, para que pueda tener una idea si está interesado o no.

Para iniciar el modo artista en emacs, haga Alt-x, escriba artist-mode y presione regresar. El botón central del mouse abre el menú. Las combinaciones de teclas para cortar y pegar no son las ventanas normales de forma predeterminada, pero puede activar el modo CUA para cambiar eso.

¿Qué piensa la gente? ¿Alguien pagaría por esto? Me gustaría.

ZOMG, encajo en una categoría similar a la tuya y me encantaría tal característica directamente en el IDE.

Por ahora solo tiendo a hacer mucho "arte" ASCII como este:

// ******************************************************
// *v3            |e5          v4*           |e6      v6*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |p1        *
// *              |            e1*-----------~----------*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *cen           |p0          v0*           |        v5*
// *--------------~--------------************************
// *e4            |              *           |e7        *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |p2        *
// *              |            e2*-----------~----------*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *v2            |e3          v1*           |e8      v7*
// ******************************************************

El valor principal que encuentro es ver los nombres de las variables correspondientes al diagrama visual, especialmente cuando estamos usando travesías complejas de mallas y cosas así para nuevos algoritmos de malla. Este truco generador de gráficos de doxygen que se muestra en una de las respuestas es súper genial, debería intentarlo más.

Hay muchas cosas que también son más fáciles de comunicar visualmente, no necesariamente usando gráficos. Ejemplo:

... o esto (comparación de mi algoritmo que estoy llamando "subdivisión de gancho" a la subdivisión CC estándar utilizada por Pixar):

Le daría al código mucho contexto para ver qué hacen estas operaciones y cómo difieren dentro del código porque algunas cosas se muestran mejor visualmente. Las imágenes realmente pueden capturar mil palabras.

Por lo tanto, sería totalmente de ensueño para mí tener un IDE que me permita ver el código y las imágenes de lado a lado, lo que me permite incrustar imágenes en el código fuente.

Especialmente cuando estamos inventando nuevos algoritmos, es difícil encontrar una buena manera de describirlos con mucha precisión (desde una perspectiva técnica, no exactamente desde la perspectiva del usuario) sin entrar en sus pasos algorítmicos, ya que no hay nada con lo que realmente compararlos directamente. Este tipo de imágenes de antes y después tienden a mostrar totalmente lo que puede esperar del algoritmo de inmediato.

Otra cosa con la que sueño es un depurador visual que me permita programarlo para que pueda hacer que algunos de mis tipos de datos muestren una imagen en el depurador, por ejemplo, para ver los resultados visualmente mientras paso por el código y me aseguro de que los algoritmos Estoy tratando de inventar, estoy trabajando correctamente en cada paso y haciendo coincidir cómo lo dibujé en papel. Por ejemplo, hacer que mi estructura de datos de malla genere una imagen renderizada en la ventana de observación del depurador, ideal si incluso pudiera rotar la vista y tal en ese mismo momento.

Además, cuando se trabaja en bases de código a gran escala (decenas de millones de LOC) escritas por equipos sueltos con un millar de complementos, a veces puede ser una pesadilla solo descubrir cómo ejecutar el código que estamos buscando por algo oscuro, plugin raramente usado de la interfaz de usuario. Sería increíble en esos casos si el código pudiera incrustar una captura de pantalla en miniatura que muestre cómo invocar ese código desde la interfaz de usuario (podría ser propenso a desactualizarse de vez en cuando, pero por lo general las IU no son tan inestables) versiones como para hacer inútiles las capturas de pantalla anteriores).

¿Alguien pagaría por esto? Me gustaría.

De todos modos, sí, ¡totalmente! ¡¡¡Quiero eso!!!

Suena como un caso de uso para la programación literaria donde puede agregar diagramas y lo que sea a su documentación.

Doxygen le permite insertar imágenes en comentarios como este:

  /*! Here is a snapshot of my new application:
   *  \image html application.jpg
   */

Desafortunadamente, parece que ningún IDE mostrará estas imágenes en línea, pero sospecho que no sería demasiado difícil escribir una extensión VSCode para hacerlo, por ejemplo.

También encontré una extensión VSCode que ya admite esto con una sintaxis commentimg diferente . Esto lo hace a través de un elemento emergente:

VSCode está agregando una función que permite imágenes en línea - "inserción de código" - pero aún no parece estar lista.

Aquí hay una captura de pantalla de la extensión de muestra (que en realidad no pude encontrar, presumiblemente aún no se ha lanzado ya que la API de inserción de código aún no se ha lanzado)