5 ms·

Code should generate diagrams automatically as you write it. Then you can see the complexity increase as you go, instead of looking back on a tangled mess.

bdg 3y ago
Our languages mostly do not have the syntax needed to express higher abstractions. You could create one via meta files or special comment notation perhaps, but it doesn't exist yet (outside of class diagram generators). A big part of this problem is the "code-model gap".
commandlinefan 3y ago
I've worked with documentation auto-generators before, and the problem they have is that they can't figure out which references are relevant and which aren't. I remember auto-generating a class diagram of a Java project in the late 90's and it showed every class having a reference to the class "java.lang.String". Generators have gotten (a little) smarter with one-off heuristics like "treat the class String as if it were a primitive", but they're still way more cluttered than a knowledgeable human would ever come up with.
- kgilpin 3y ago
  What we do with appmap.io is to depict only your own code and not dependencies. Also, each diagram depicts a runtime trace and not just static imports. It produces a more focused diagram, and it also clearly illuminates factors like HTTP client and server requests, and SQL, that static analysis can’t see. The data can be depicted as a dependency map, sequence diagram, detailed trace, and flame graph.
SkyPuncher 3y ago
How do you do that with disparate, disconnected systems?
- vaughan 3y ago
  Parse all the code with tree-sitter[1]. [1]: https://tree-sitter.github.io/tree-sitter/ https://tree-sitter.github.io/tree-sitter/
Supermancho 3y ago
> Code should generate diagrams automatically as you write it. That's fine for some purposes, but for general discussions around many subjects (project planning, security, integration testing, etc) you won't get there from generated diagrams out of some code in an application.

bdg 3y ago

Our languages mostly do not have the syntax needed to express higher abstractions. You could create one via meta files or special comment notation perhaps, but it doesn't exist yet (outside of class diagram generators). A big part of this problem is the "code-model gap".

commandlinefan 3y ago

I've worked with documentation auto-generators before, and the problem they have is that they can't figure out which references are relevant and which aren't. I remember auto-generating a class diagram of a Java project in the late 90's and it showed every class having a reference to the class "java.lang.String". Generators have gotten (a little) smarter with one-off heuristics like "treat the class String as if it were a primitive", but they're still way more cluttered than a knowledgeable human would ever come up with.

kgilpin 3y ago
What we do with appmap.io is to depict only your own code and not dependencies. Also, each diagram depicts a runtime trace and not just static imports. It produces a more focused diagram, and it also clearly illuminates factors like HTTP client and server requests, and SQL, that static analysis can’t see. The data can be depicted as a dependency map, sequence diagram, detailed trace, and flame graph.

SkyPuncher 3y ago

How do you do that with disparate, disconnected systems?

vaughan 3y ago
Parse all the code with tree-sitter[1]. [1]: https://tree-sitter.github.io/tree-sitter/ https://tree-sitter.github.io/tree-sitter/

Supermancho 3y ago

> Code should generate diagrams automatically as you write it. That's fine for some purposes, but for general discussions around many subjects (project planning, security, integration testing, etc) you won't get there from generated diagrams out of some code in an application.