4 ms·

> You generally can’t auto-generate useful [architecture diagrams] from code, The question is: why is this the case? IMNSHO, the reason is that we don't have

> You generally can’t auto-generate useful [architecture diagrams] from code, The question is: why is this the case? IMNSHO, the reason is that we don't have a way to express architecture in or as code. Instead, we have to compile the actual architecture of the system into one that is expressible using the call/return architectural style that our programming languages support. That's a lossy process. When we can program with actual architectural connectors, auto-generating useful architectural diagrams becomes trivial. https://objective.st https://objective.st

vlovich123 3y ago
I don’t think that’s the problem. There are so many different ways to look at a system. An architectural diagram shows you how components connect. A procedural diagram shows you what steps a program takes. An entity diagram shows you the major high level entities you’ve selected into your system. I just don’t see how a single language can express all the detail. Maybe a new one can be invented but I don’t see how S expressions solve this (the link you posted don’t have any indication that any diagram generation is part of the language). Also, diagrams can be useful even if they have birotted because discrepancies are a good teaching tool - “why does this diagram say x but the code seems to do y” is a tracing opportunity, an opportunity to update the diagram, and highlights which engineers are paying attention. Maybe if LLMs get sufficiently advanced they can generate this stuff more automatically with some minor prompting with the code as context, but I doubt it. Not until AI can actually start understanding sentiment from code.
- mpweiher 3y ago
  > An architectural diagram shows you how components connect. That's the one we're talking about here. > A procedural diagram shows you what steps a program takes Which is useful if the program is procedural. > An entity diagram shows you the major high level entities you’ve selected into your system. That's the top-level of your architectural diagram. > I just don’t see how a single language can express all the detail. When the program's architectural style is call/return, we can do this just fine. Using stepwise refinement we move up and down the abstraction ladder of our system and thus add/remove detail. No problem. The problem is that most systems these days are not primarily call/return, but have to be programmed in call/return languages. > I don’t see how S expressions solve this I don't either, and have no idea what S expressions have to do with this. > .... diagram generation is part of the language It's not part of the language. But it's part of the frameworks, and when the abstractions of your language are architectural in nature, there is a very close correspondence between the code and the diagrams. > ... discrepancies are a good teaching tool... Yes, since the diagrams are generated, it's easy to keep older version around and generate new ones on-demand. Then you can check the differences visually, in code, or as the difference between code and diagram. Take your pick. > Not until AI can actually start understanding sentiment from code. Again, the point is that architecture is not actually "sentiment". It is structural. The fact that it looks like sentiment in practice is purely a side effect of our programming languages being incapable of encoding architecture in the general case.
rewmie 3y ago
> The question is: why is this the case? Diagrams capture and represent abstract and/or high level concepts. Their goal is to provide a kind of mental map of how specific aspects of a project are organized in order to help developers form their mental models. This means placing the focus on key constructs and downplaying the importance or relevance of other components. There isn't an objective way to provide a one-to-one mapping between what bits of a software project are of critical importance to form mental models, and what bits are irrelevant. > IMNSHO, the reason is that we don't have a way to express architecture in or as code. Not true. We have more than plenty of ways to represent software architectures. That is trivial and a solved problem. So is mapping representations of software architectures to (some) source code, at least in the form of skeleton code. The problem lies in mapping software projects to a software architecture, even when the software project is clean and a textbook example of a very specific software architecture.
- mpweiher 3y ago
  You are confusing “implement” and “express” If the architecture were directly expressed in the code, mapping back would be trivial. It is not because we effectively compile the actual architecture in order to express it in code. Mapping back then becomes decompiling, with the added complications of architectural mismatch and manual compilation.

vlovich123 3y ago

I don’t think that’s the problem. There are so many different ways to look at a system. An architectural diagram shows you how components connect. A procedural diagram shows you what steps a program takes. An entity diagram shows you the major high level entities you’ve selected into your system. I just don’t see how a single language can express all the detail. Maybe a new one can be invented but I don’t see how S expressions solve this (the link you posted don’t have any indication that any diagram generation is part of the language). Also, diagrams can be useful even if they have birotted because discrepancies are a good teaching tool - “why does this diagram say x but the code seems to do y” is a tracing opportunity, an opportunity to update the diagram, and highlights which engineers are paying attention. Maybe if LLMs get sufficiently advanced they can generate this stuff more automatically with some minor prompting with the code as context, but I doubt it. Not until AI can actually start understanding sentiment from code.

mpweiher 3y ago
> An architectural diagram shows you how components connect. That's the one we're talking about here. > A procedural diagram shows you what steps a program takes Which is useful if the program is procedural. > An entity diagram shows you the major high level entities you’ve selected into your system. That's the top-level of your architectural diagram. > I just don’t see how a single language can express all the detail. When the program's architectural style is call/return, we can do this just fine. Using stepwise refinement we move up and down the abstraction ladder of our system and thus add/remove detail. No problem. The problem is that most systems these days are not primarily call/return, but have to be programmed in call/return languages. > I don’t see how S expressions solve this I don't either, and have no idea what S expressions have to do with this. > .... diagram generation is part of the language It's not part of the language. But it's part of the frameworks, and when the abstractions of your language are architectural in nature, there is a very close correspondence between the code and the diagrams. > ... discrepancies are a good teaching tool... Yes, since the diagrams are generated, it's easy to keep older version around and generate new ones on-demand. Then you can check the differences visually, in code, or as the difference between code and diagram. Take your pick. > Not until AI can actually start understanding sentiment from code. Again, the point is that architecture is not actually "sentiment". It is structural. The fact that it looks like sentiment in practice is purely a side effect of our programming languages being incapable of encoding architecture in the general case.

rewmie 3y ago

> The question is: why is this the case? Diagrams capture and represent abstract and/or high level concepts. Their goal is to provide a kind of mental map of how specific aspects of a project are organized in order to help developers form their mental models. This means placing the focus on key constructs and downplaying the importance or relevance of other components. There isn't an objective way to provide a one-to-one mapping between what bits of a software project are of critical importance to form mental models, and what bits are irrelevant. > IMNSHO, the reason is that we don't have a way to express architecture in or as code. Not true. We have more than plenty of ways to represent software architectures. That is trivial and a solved problem. So is mapping representations of software architectures to (some) source code, at least in the form of skeleton code. The problem lies in mapping software projects to a software architecture, even when the software project is clean and a textbook example of a very specific software architecture.

mpweiher 3y ago
You are confusing “implement” and “express” If the architecture were directly expressed in the code, mapping back would be trivial. It is not because we effectively compile the actual architecture in order to express it in code. Mapping back then becomes decompiling, with the added complications of architectural mismatch and manual compilation.