Community
Chat Logs
Thursday, May 14, 2026
- jreicherOh, since UML just got mentioned, I have a dumb question: how, just for your own use, would you document a really complicated type hierarchy that you've written?
- jreicherI would turn to UML because it's what I know, but it's been ages since I've looked at modern techniques.
- cheeseri would happily use UML's class diagrams for that. UML is actually great. it's all the ceremony that grew up around it.
- cheeserUML diagrams are used all the time in documentation, presentations, etc. look at documentation on, say, network connection and protocol negotiation.
- Drixtaneach time I write some analysis documents, I include UML and people LOVE it
- jreicherGood to hear. I'm still quite fond of it (for type hierarchies in particular)
- ParaIf the structure is stable, UML is fine.
- ParaThere's also a javadoc extension somewhere which can autogenerate UML for class hierarchies as part of the class documentation and embed it into the docs.
- ParaSo that's one way; actually write the Javadocs and use that extension on top (if it still exists and works, of course) :)
- Parahttps://github.com/talsma-ict/umldoclet this one seems to be up-to-date and active
- javabotPara's title: "GitHub - talsma-ict/umldoclet: Automatically generate PlantUML diagrams in javadoc · GitHub"
- Para~jep 467
- javabot'JEP 467: Markdown Documentation Comments' can be found at http://openjdk.java.net/jeps/467
- nevetJEP 467: Markdown Documentation Comments
- jreicherI worry that I would go to the trouble of learning how to use a tool like that, and then it would crash on code. The hierarchy is really, really not simple.
- jreicherOr if not crash, then maybe still generate something unpleasant.
- ParaThere's one easy way to find that out.
- DrixtanI find UML interesting when it shows only the parts of what I am describing: an UML of a whole system is kind of flooding the reader with too much boxes and it becomes hard to follow, or even render at that point. Generation is great for small systems, but at the end, I think the power of UML is to describe something at a high level, not to fully document a system. It adds to the documentation imo. A good example of what I am trying to convey here is when you
- Drixtanare looking for "design patterns"; they usually come with an UML diagram to explain only that part.
- jreicherOne of the things I like about UML is the division between structure and behaviour. I think it's really important to cut away the state change to understand a system's structure.
- ParaDrixtan: which is why I nowadays only do exclusively https://c4model.com/ for architecture stuff
- nevetHome
- Paraand obviously not manually but with https://github.com/plantuml-stdlib/C4-PlantUML
- nevetGitHub - plantuml-stdlib/C4-PlantUML: C4-PlantUML combines the benefits of PlantUML and the C4 model for providing a simple way of describing and communicate software architectures
- javabotPara's title: "GitHub - plantuml-stdlib/C4-PlantUML: C4-PlantUML combines the benefits of PlantUML and the C4 model for providing a simple way of describing and communicate software architectures · GitHub"
- ParaI should probably blog about how to efficiently build composable C4 diagrams with that. There's a few import tricks one can do to have subsystems etc. in their own diagrams with proper links etc.
- DrixtanPara: I didn't know about C4, thank you for sharing. If you happen to write that blog post, I am interessted to get the URL.
- ParaDrixtan: https://arc42.org/ for the wordy part
- nevetarc42
- ParaAlso I don't have a blog because as a true enginöör I'm overcomplicating the platform. I've compared it to what nevet is for dreamreal , I have the most awesome single-node infra setup for the blog and it's missing frontend ;D
- Drixtanone day, one day... ;)
- deebothere was some okayish plugin for idea to generate plantuml from database schemas, types etc
- Parayeh, and it works directly with the linked c4-plantuml
- dreamrealjreicher: I've used UML in my books, mostly because the publishers asked for it specifically; a complex type hierarchy ... is unfortunate. I don't think UML actually HELPS, but it CAN document such things.
- dreamreal"See this snarled rat's nest of a class hierarchy? UML and plantuml can organize it somewhat to make it less rat's-nest-ier. Okay, next topic..."
- dreamrealPara: https://github.com/nooga/xsofy
- nevetGitHub - nooga/xsofy: Roguelike that names itself each run. WIP
- javabotdreamreal's title: "GitHub - nooga/xsofy: Roguelike that names itself each run. WIP · GitHub"
- DoofusCanadensis"names itself each run"? the heck is that supposed to mean?
- dreamrealit makes up a name every run
- dreamreal"the goblet of inconsequence" first, then "the chalice of goblets" second run, etc etc etc
- jreicherI'm quite looking forward to getting a diagram for my type hierarchy in the end. The only reason I haven't done it yet is I'm still working on it, but I think a diagram will be very useful when it's done, even though it's complicated.