3 ms·

This isn't a very good solution, IMHO. Or, it doesn't scale. If you find yourself with an existing solution that doesn't scale for what you need it to, cut your

This isn't a very good solution, IMHO. Or, it doesn't scale. If you find yourself with an existing solution that doesn't scale for what you need it to, cut your losses and find a better tool or solution. Some simple visualization using ASCII is fine. Something you can create from scratch and otherwise modify in as much time as it would take to document code. But, if you need a sequence diagram, or flow chart, what not. The tradeoff for maintenance and lack of readability makes it look silly. The "why was this developer wasting time doing things with the wrong tools"-kind of silly. If you need complex diagrams. Create them using draw.io or plantuml, and add them to the source control. Generate images which you instead reference in the documentation in code. Tools such as Doxygen and other such tools would be able to pull in the images and actually look good. This is both maintainable, and scalable.

machinerychorus 4y ago
I'm not sure I agree with "it doesn't scale". It scales just as well as writing code by hand does! PlantUML/mermaidjs do hit a sweet spot IMO, of having the chart defined as plaintext but rendering a pretty picture. The only way these could be improved IMO is if the ascii "code" for the diagram was also an actual diagram you could understand without running it through the parser.
- okamiueru 4y ago
  I should clarify what I mean with scaling. I was trying to describe complexity of maintaining the illustration for the complexity of what it is illustrating. For ASCII art, this is far from linear, in most of the examples shown. Consider some of the more complex ones shown in the linked article. The minor added complexity of adding a field, suddenly might mean you need to remake parts, or even entire visual art for it to stay congruent. You'll have software engineers hitting spacebar a few hundred times just to align things right. With proper tools, you'd just add the field, and that's it.
unholiness 4y ago
Any visual information that needs to be understood by a human doesn't scale. ASCII UMLs might scale slightly less well than, say, powerpoint UMLs, but having them right there in the code comment in cases that do fit is splendid.

machinerychorus 4y ago

I'm not sure I agree with "it doesn't scale". It scales just as well as writing code by hand does! PlantUML/mermaidjs do hit a sweet spot IMO, of having the chart defined as plaintext but rendering a pretty picture. The only way these could be improved IMO is if the ascii "code" for the diagram was also an actual diagram you could understand without running it through the parser.

okamiueru 4y ago
I should clarify what I mean with scaling. I was trying to describe complexity of maintaining the illustration for the complexity of what it is illustrating. For ASCII art, this is far from linear, in most of the examples shown. Consider some of the more complex ones shown in the linked article. The minor added complexity of adding a field, suddenly might mean you need to remake parts, or even entire visual art for it to stay congruent. You'll have software engineers hitting spacebar a few hundred times just to align things right. With proper tools, you'd just add the field, and that's it.

unholiness 4y ago

Any visual information that needs to be understood by a human doesn't scale. ASCII UMLs might scale slightly less well than, say, powerpoint UMLs, but having them right there in the code comment in cases that do fit is splendid.