Comment by bakatubas | Hacker News Reader

Comment by bakatubas | Hacker News Reader

Parent Full thread

I dunno I disagree—the fact is a lot of people just dive into coding and don’t spend much time with design.

There’s a ton of value in the idea of diagramming code and then generating sources. UML is a starting point but the journey is far from over.

The more appropriate idea is that you create documentation in the form of diagrams for free. Just like in TDD you get unit-tests for free.

Folks always talk about self-documenting code—and that’s great. But what about conveying a complex system to a new team of engineers? Diagrams are frankly priceless if done well.

Also, looking at something like Kubernetes where a declarative YAML file generates magic underneath is somewhat similar. A step beyond what we have would be nice diagramming capabilities over the YAML to auto generate the plumbing underneath.

Personally, I think future advances in development _will_ be done as higher level ideas—pictures worth a thousand lines of code—AI will do the rest.

> The more appropriate idea is that you create documentation in the form of diagrams for free.

The problem is the diagrams are hard to create and hard to update and usually don't remain synchronized to the code. If there was a good way to create documents from the code (perhaps with some annotations required), it could just be a Make target and boom, free(ish) documentation.

I’ve recently gotten reacquainted with Doxygen, and it allows you to embed PlantUML source right in your source code or Markdown files. Easy to write, easy to update, and stored as plaintext right in your source tree. I don’t love Doxygen, but it’s doing a great job at what I’m trying to do (document a complex C++ project)

What about org-mode? I am using plantUML in org-mode.

I use PlantUML in org-mode as well! That's actually where I started, but found it much easier to recruit other people to write their own documentation (with sequence and state diagrams) by not requiring them to use Emacs :)

I'm working on this, for Ruby, Python, and Java - https://appland.com/docs/get-started.html - would love to get your feedback.

I feel like my ideal workflow would be a middleground between doing the design up front and just jumping into coding. Before you start coding I feel like you don't have much of an idea of what problems you will run into, resulting in diagrams based on the wrong assumptions. But with code it's easy to loose track of the high level structure of what you are writing. Writing code, then diagramming the high level structure, and then going back to fix the code seems like a good way to go.

Absolutely! That is similar to artists doing thumbnail sketches to figure out the composition; then once things are reasonably worked out, the chosen composition can be worked onto the final canvas; then the details follow.

That is a nice benefit of good development frameworks: how easy is it to explore new ideas? And frankly that’s why there’s an uptick in higher level languages.

> diagramming capabilities over [Kubernetes] YAML

Has been tried: https://github.com/CATechnologiesTest/yipee

Granted, but you can do the same and much more with different methods, and avoid fighting the frustrating, unreliable and time-consuming UML tools altogether.

I can’t argue _for_ any particular tool—just that the concept is a really good concept.

I think a lot of it comes down to folks not bothering to invest in making good tools—or developers sticking to their current workflow.

That is why I relate it to Test-Driven Development because it does require a shift in process. But the end result, I think, could be very rewarding.

Reply on news.ycombinator.com