Anotar código fonte com diagramas como comentários

Eu escrevo muito código (principalmente c ++ e javascript) que aborda geometria computacional e gráficos e esses tipos de tópicos, então descobri que os diagramas visuais têm sido uma parte indispensável do processo de solução de problemas.

Eu determinei agora que "oh, não seria fantástico se de alguma forma eu pudesse anexar um diagrama desenhado a mão a um pedaço de código como um comentário", e isso me permitisse voltar para algo em que trabalhei, dias, semanas, meses antes e muito mais rapidamente re-grok meus algoritmos.

Como aprendiz visual, sinto que isso tem o potencial de melhorar minha produtividade com quase todos os tipos de programação, pois diagramas simples podem ajudar a entender e raciocinar sobre qualquer tipo de estrutura de dados não trivial. Gráficos, por exemplo. Durante as aulas de teoria dos grafos na universidade, eu só consegui compreender verdadeiramente as relações gráficas das quais eu realmente podia desenhar representações diagramáticas.

Então...

Nenhum IDE que eu saiba permite salvar uma imagem como comentário no código.

Meu pensamento era que eu ou outra pessoa poderia criar uma ferramenta razoavelmente fácil de usar que possa converter uma imagem em uma string binária base64 que eu possa inserir no meu código.

Se o processo de conversão / inserção puder ser simplificado o suficiente, permitiria uma conexão muito melhor entre o diagrama e o código real, portanto, não preciso mais pesquisar cronograficamente através dos meus cadernos. Ainda mais impressionante: plugins para os IDEs analisarem e exibirem a imagem automaticamente. Não há absolutamente nada de difícil nisso do ponto de vista teórico.

Meu palpite é que levaria algum tempo extra para eu realmente descobrir como estender meus IDEs favoritos e manter esses plug-ins, então eu ficaria totalmente feliz com um tipo de pós-processador de código que faria o mesmo analisando e renderização das imagens e mostrá-las lado a lado com o código, dentro de um navegador ou algo assim. Desde que eu sou um programador javascript por profissão.

O que as pessoas pensam? Alguém pagaria por isso? Eu gostaria. Mas talvez eu também indique que, independentemente de eu ou algum número significativo de meus colegas pagar por isso, a única maneira de obter sucesso seria com um lançamento de código aberto.

E o plug-in de inserção de imagem do Visual Studio ?

Se você estiver usando um IDE diferente e ele não suportar imagens incorporadas ou não tiver tempo para estendê-lo, que tal colocar um link para uma imagem nos comentários, enquanto a imagem residiria em algum lugar do repositório ?

Se você não é um artista ASCII , pode usar o doxygen como ferramenta de documentação junto com o dot / graphviz integrado a ele.

Isso permite escrever uma descrição textual dos gráficos e renderizá-los na documentação.

Por exemplo, esta descrição:

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)" ];
}

renderiza como:

Você pode experimentar o modo de artista do emacs. Seria arte ascii em vez de imagens em si, por isso pode ou não ser o que você está procurando. Em particular, se o seu IDE não executar fontes de largura fixa, não seria útil. Sendo texto simples, ele seria muito bem reproduzido com o controle de versão.

Aqui está um screencast do modo artista sendo usado, para que você possa ter uma ideia se estiver interessado ou não.

Para iniciar o modo artist no emacs, pressione Alt-x, digite artist-mode e pressione return. O botão do meio do mouse exibe o menu. As combinações de teclas para recortar e colar não são as normais do Windows por padrão, mas você pode ativar o modo CUA para alterar isso.

O que as pessoas pensam? Alguém pagaria por isso? Eu gostaria.

ZOMG, eu me encaixo em uma categoria semelhante à sua e adoraria esse recurso diretamente no IDE.

Por enquanto, apenas costumo fazer muita "arte" ASCII como esta:

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

O principal valor que encontro é ver os nomes de variáveis ​​correspondentes ao diagrama visual, especialmente quando estamos usando passagens complexas de malhas e tal para novos algoritmos de malha. Esse truque de geração de gráfico doxygen mostrado em uma das respostas é super legal - eu deveria tentar mais.

Existem muitas coisas que são mais fáceis de se comunicar visualmente, nem mesmo usando gráficos. Exemplo:

... ou isso (comparação do meu algoritmo que estou chamando de "subdivisão do gancho" com a subdivisão CC padrão usada pela Pixar):

Isso daria muito contexto ao código para apenas ver o que essas operações fazem e como elas diferem dentro do código, porque algumas coisas são apenas mostradas visualmente. As imagens podem realmente capturar mil palavras.

Portanto, seria totalmente sonhador para mim ter um IDE que me permitisse ver código e imagens lado a lado, permitindo incorporar imagens no código-fonte.

Especialmente quando estamos inventando novos algoritmos, é difícil encontrar uma boa maneira de descrevê-los com muita precisão (de uma perspectiva técnica, não exatamente da perspectiva do usuário) sem entrar em suas etapas algorítmicas, pois não há nada para realmente compará-los diretamente. Esses tipos de imagens antes e depois tendem a mostrar totalmente o que você pode esperar do algoritmo imediatamente.

Outra coisa que eu sonho é com um depurador visual que me permite programá-lo para que alguns tipos de dados produzam uma imagem no depurador, por exemplo, para ver os resultados visualmente enquanto passo o código e certificando-me de que os algoritmos Estou tentando inventar que estão funcionando corretamente a cada passo e combinando como eu o escrevi no papel. Por exemplo, faça com que minha estrutura de dados de malha produza uma imagem renderizada na janela de inspeção do depurador - ideal se eu pudesse girar a visualização e outras coisas naquele momento.

Além disso, ao trabalhar em bases de código de grande escala (dezenas de milhões de LOC) escritas por equipes soltas com mil plug-ins, às vezes pode ser um pesadelo descobrir como executar o código que estamos procurando por algo obscuro, plug-in raramente usado na interface do usuário. Seria incrível nesses casos se o código pudesse incorporar uma captura de tela em miniatura mostrando como realmente chamar esse código a partir da interface do usuário (pode ser propenso a ficar desatualizado de tempos em tempos, mas geralmente as UIs não são tão instáveis ​​entre elas versões para tornar inúteis os screenshots anteriores).

Alguém pagaria por isso? Eu gostaria.

Enfim, sim, totalmente! Eu quero aquilo!!!

Soa como um caso de uso para programação alfabética, onde você pode adicionar diagramas e qualquer outra coisa à sua documentação.

O Doxygen permite inserir imagens em comentários como este:

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

Infelizmente, parece que nenhum IDEs exibirá essas imagens em linha, mas suspeito que não seria muito difícil escrever uma extensão VSCode para fazê-lo, por exemplo.

Eu também encontrei uma extensão VSCode que já suporta isso com uma sintaxe diferente commentimg . Isso é feito através de um hover:

O VSCode está adicionando um recurso que permite imagens embutidas - "inserção de código" -, mas ainda não parece estar pronto.

Aqui está uma captura de tela da extensão de amostra (que eu realmente não consegui encontrar - presumivelmente ainda não foi lançada porque a API de inserção de código ainda não foi lançada)