Anotar código fuente con diagramas como comentarios

14

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.

Steven Lu
fuente
44
Una alternativa: comentar en un enlace a un archivo de imagen local que se abre en el visor de imágenes predeterminado.
Hand-E-Food
Mi mayor temor sería el abuso del sistema. Claro que comienza con un diagrama significativo para un algoritmo complejo, pero ¿cuánto tiempo hasta que alguien cargue documentos de especificación endebles en los comentarios para la clase? Antes de que te des cuenta, todo lo relacionado con el proyecto + desarrollador se incluye en comentarios de código. Por supuesto, cualquier sistema poderoso está abierto al abuso. Creo que la necesidad es un nicho, pero si estás en ese nicho, sería una herramienta muy útil.
Snixtor
@ Hand-E-Food Nice! Una URL de archivo en un comentario aparece como un enlace en el que se puede hacer clic en Xcode fuera de la caja. Mi única queja con esto es que parece imposible crear una URL de archivo de ruta relativa, por lo que el aspecto del enlace en el que se puede hacer clic se rompe (con toda probabilidad) al cambiar de sistema.
Steven Lu
Te pueden interesar los gráficos o árboles
TehShrike
Hago javadoc que generará HMTL, con imágenes. O SimpleDocBook, documentación separada, basada en XML, uno puede / debe hacer referencia en el código para las reglas de negocios. Eso ofrece una buena prosa y cubre el sistema desde la perspectiva de toda la lógica empresarial, en lugar de distribuir componentes y capas de software (clases). Cada solicitud de cambio, agrega un código con referencia al número de docbook + versión / ticket, y el docbook tiene una lista de cambios + número de ticket. Eso funciona debido a su cobertura completa. No estoy seguro de cómo se adaptaría a su situación.
Joop Eggen el

Respuestas:

6

¿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? ?

Arseni Mourzenko
fuente
Eso es muy bonito. Yo uso VS en el trabajo, ¡así que podría probarlo! Gracias. Guardar la imagen en el repositorio y vincularla de alguna manera es definitivamente una forma de lograr esto, pero estoy bastante seguro de que todavía es demasiado trabajo de contabilidad para implementar de manera confiable. Soy un programador bastante vago.
Steven Lu
Guardar las imágenes en el repositorio también funcionaría con la mayoría de los métodos de exploración de repositorios (por ejemplo, la interfaz web del repositorio VCS)
Steven Lu
4

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:

ingrese la descripción de la imagen aquí

Mouviciel
fuente
¡Esta genial! ¿Alguna herramienta de soporte para entornos Java? No puedo ver nada parecido al soporte para esto en este Mojo, por ejemplo: graphviz-maven-plugin.bryon.us/dot-mojo.html . Todos los demás también han tenido soporte para archivos .dot.
oligofren
2

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.

Michael Shaw
fuente
Wow eso es ... impresionante. De hecho, tengo algunos comentarios de estilo de diagrama ASCII en mi código. Es demasiado tiempo. Voy a querer usar mejores herramientas porque la tecnología ya está aquí. Solía ​​escribir código en Vim a veces, pero qué scripts de reconocimiento de código me quedaban cortos en comparación con los IDE reales. ¡Pero gracias por mostrarme esta técnica de la vieja escuela!
Steven Lu
Visité unos años más tarde y desde entonces he reunido algunas golosinas de Vim para ayudar a ensamblar rápidamente diagramas de caja. Ya sea que se trate de caracteres de cuadro ASCII o Unicode, esta es una forma muy genial de embellecer algún código con comentarios geniales y útiles. Sin embargo, Vim no viene con nada de la caja.
Steven Lu
1

¿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:

ingrese la descripción de la imagen aquí

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

ingrese la descripción de la imagen aquí

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!!!


fuente
1
¡Imágenes impresionantes y gracias por la reseña (aunque probablemente sea más un comentario que una respuesta)! Recientemente he decidido tomar un descanso por completo de gráficos y simulación y crear herramientas de depuración y rastreo de última generación . Lo que sueñas son muy similares a las cosas con las que sueño ...
Steven Lu
1
@StevenLu He soñado a menudo con hacer este tipo de IDE que propones con el depurador visual (aunque estaba pensando en hacerlo desde cero ya que no podía imaginar una solución de complemento que hiciera tan bien el lado del depurador). Pero sí, supongo que esa respuesta fue una especie de comentario ... pero estaba tan feliz de ver a alguien más deseando eso. Mis compañeros de trabajo en el pasado eran más técnicos y matemáticos: no entendían mi deseo de comunicar todo visualmente.
1
Quizás una forma pseudocientífica de verlo es que el sistema visual es de lejos la interfaz de mayor ancho de banda que tenemos como humanos, y aunque apesta que solo lo tengamos disponible para usar como entrada, la profunda integración del sistema visual en El acceso a la memoria cerebral permite a los formatos visuales una ventaja inequívoca para la documentación y la difusión de conceptos abstractos. ... Con ese fin, estoy trabajando en una herramienta independiente de IDE (siguiendo la filosofía de Unix) que permite que las aplicaciones compiladas generen automáticamente representaciones visuales estructuradas de sus componentes internos para que podamos entenderlos.
Steven Lu
0

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

Restablece a Mónica - M. Schröder
fuente
¿Por qué el voto negativo?
Restablece a Monica - M. Schröder
Te he votado. Es una muy buena observación, lo que estoy discutiendo cae casi por completo bajo ese paraguas.
Steven Lu
1
También voté en contra porque esto realmente no proporciona una respuesta. Claramente, no quiere cambiar todo su programa a un estilo de programación alfabetizado, e incluso si lo hizo, la programación alfabetizada es solo un enfoque de la programación; no necesariamente significa que los diagramas y las imágenes sean compatibles.
Timmmm
0

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)

Timmmm
fuente