Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: Is there a better way to document complex software architectures?

news.ycombinator.com

Post reply on HN
Print view View original

211–220 of 239 posts

Re: Ask HN: Is there a better way to document complex software architectures?

#211

Post by jonathanlydall »

taeric wrote: post #207
vruiz wrote: post #157

Earlier quoted context omitted.

Speaking as someone who checks in other kinds of generated code. The tool, like any software, can have bugs/changes in behavior across versions. You don't want to introduce the chance of that happening without being audited in version control if you can easily avoid it.

The tool should be referenced as a versioned dependency at build time. When it gets a new release, you do a new build. Complete with new tests. Anything you do that increases the time between the introduction of the bug and the finding of the bug will make it harder to actually fix it.

In addition to my reply above about code-weaving, rather than the all or nothing approach that some code generation techiniques suffer, our tool allows proposed changes to be reviewed before you commit with writing the generated code to your disk.

This allows developers to feel in control of what's changing in their code base during generation, rather than being worried that some custom code is going to get wiped out by code-gen without them realizing.

In a past project I was on, we had our solution build process run T4 templates to generate code, and it significantly slowed down the build process.

We feel code generation is something you explicitly do when you're "modelling", it's not something that's necessary to create a build nor should it create run-time dependency.

Re: Ask HN: Is there a better way to document complex software architectures?

#212

Post by jonathanlydall »

derangedHorse wrote: post #158
rocqua wrote: post #115

Earlier quoted context omitted.

I can envision two reasons. The first is that, in truth, the code generated from the UML, isn't good enough and people still actually work on the output. The second guess is that humans occasionally rewrite the code for optimization. It might then be easier to source controll the code rather than patches.

There's also the reason of not wanting to generate all the code every single time someone new retrieves the repo or needs to revert back to a previous commit.

Completely our thinking too. Code generation should not be a build or run time dependency.

Our tool also allows developers to review proposed code changes before choosing to commit them to disk.

Code generation is something you choose to do explicitly as you model.

Re: Ask HN: Is there a better way to document complex software architectures?

#213

Post by jonathanlydall »

taeric wrote: post #208
derangedHorse wrote: post #158

Earlier quoted context omitted.

There's also the reason of not wanting to generate all the code every single time someone new retrieves the repo or needs to revert back to a previous commit.

This reason doesn't make sense. Again, do you checkin the bytecode of your java? I'd expect you, instead, to recompile the java every time you do a build. Now, I would expect you to have an artifact repository. To that end, you would be able to easily get the generated sources. But, they would decidedly not be in the source repository.

I don't feel the bytecode comparison makes sense, because the generated code is human readable, bytecode is (to almost all intents and purposes) not.

We feel that code generation is something one does explicitly while modelling, not something done every time you build.

Re: Ask HN: Is there a better way to document complex software architectures?

#214

Post by jonathanlydall »

tachang wrote: post #42
jonathanlydall wrote: post #39

Full disclosure: I am one of the developers of a product which does the below, also known as model driven architecture. For about 5 years now, the teams I have been on have found great success in the use of DDD. Towards this we have used a tool which not only allows us to visually model the domain using UML, but also performs what we call “code management” (smarter code-gen which doesn’t get in your way, or produce u…

What product is it?

Intent Architect[1].

Our main development focus right now is on usability for new comers and we're improving it regularly.

[1] http://intentarchitect.com/

Re: Ask HN: Is there a better way to document complex software architectures?

#215

Post by jonathanlydall »

maccio92 wrote: post #73
jonathanlydall wrote: post #39

Full disclosure: I am one of the developers of a product which does the below, also known as model driven architecture. For about 5 years now, the teams I have been on have found great success in the use of DDD. Towards this we have used a tool which not only allows us to visually model the domain using UML, but also performs what we call “code management” (smarter code-gen which doesn’t get in your way, or produce u…

What is the tool?

Intent Architect[1].

Our main development focus right now is on usability for new comers and we're improving it regularly.

[1] http://intentarchitect.com/

Re: Ask HN: Is there a better way to document complex software architectures?

#216

Post by jonathanlydall »

t3hprofit wrote: post #109
jonathanlydall wrote: post #39

Full disclosure: I am one of the developers of a product which does the below, also known as model driven architecture. For about 5 years now, the teams I have been on have found great success in the use of DDD. Towards this we have used a tool which not only allows us to visually model the domain using UML, but also performs what we call “code management” (smarter code-gen which doesn’t get in your way, or produce u…

re: full disclosure, I appreciate your reply and that it didn't end with "So, you should use program X (the one you work on) because it's the best software". Your objective response is great.

Thank you, regardless of my interests in promoting the idea of using such a tool, we made it because we have found time and time again that always upto date visual documentation such as UML is invaluable, especially as projects get older and bigger.

Otherwise, in general we're far more interested in constructive criticism (or even just normal criticism) of our philosophy (and tool) from a place like HN, rather than trying to score a little free "advertising". When the time is right, we'll do proper promotion, and it won't be by spamming forums.

Re: Ask HN: Is there a better way to document complex software architectures?

#217

Post by basdp »

mden wrote: post #161
basdp wrote: post #123

Earlier quoted context omitted.

All the time.

My initial impression is the same as the parent. Juxtaposing microservices and KISS seems weird as the "architectural complexity" of microservices is several times higher than a monolith. You're not only multiplying the points of failure but also increasing the difficulty of translating the domain into code, especially when it comes to reading and writing from a db in a safe and efficient manner. Someone will need to…

The problem with this approach is that it might be easier to build a monolith, maintaining it and the ops side of it is far more complex.

Re: Ask HN: Is there a better way to document complex software architectures?

#218

Post by basdp »

jimjimjim wrote: post #127
basdp wrote: post #122

Earlier quoted context omitted.

So you're calling (f.e.) Amazon a shack?

And the Burj Khalifa doesn't need an architect? Sometimes the system doesn't need it sometimes it does. Not all software systems are the same. I personally think the architect role is to look at the big picture first rather than trying to dictate the minutiae.

The point is that an architect who doesn't 'code' (read: doesn't know how the practical implementation is done) doesn't know what he is designing. It's too abstract.

A structural architect is called the same, but is not really comparable. Apples and oranges. At the least because the Burj Khalifa is still built under the same physics model as they used 100 years ago.

Re: Ask HN: Is there a better way to document complex software architectures?

#219

Post by theknarf »

I used MagicDraw in a previous job, it's decent. We had it setup so that we actually generated C++ class's from parts of the UML. As well as generating powerpoint and word/pdf documents from it. MagicDraw also comes with its own version control system so that everything can live centrally on the companies server.

I do wish that it integrated with Git, and that the app was slightly faster / less bloated, but all in all; it was a much better experience than Visio & PowerPoint. These days I'm unfortunately back on PowerPoint architecture.

Enterprise Architect and MagicDraw are as far as I know the two most popular UML diagramming tools.

Re: Ask HN: Is there a better way to document complex software architectures?

#220

Post by pron »

sagichmal wrote: post #137
agentultra wrote: post #72

Earlier quoted context omitted.

Ok, some teams at Amazon: https://lamport.azurewebsites.net/tla/formal-methods-amazon.... Also it's not very readable and cannot document many design aspects e.g. the reasons behind technical decisions. Not very readable? How so? I'd rather read a concise mathematical definition rather than three pages of prose and diagrams. It is most definitely readable although it does require some training to understand the mathe…

> Not very readable? How so? I'd rather read a concise mathematical definition rather than three pages of prose and diagrams. It is most definitely readable although it does require some training to understand the mathematics if you're not used to reading it. Just as reading a blueprint requires a bit of training. You glibly toss off "a bit of training" as if it's an afternoon's work over a cup of coffee. Understandi…

> Understanding, intuitively, the systems that mathematical models like TLA describe is _extraordinarily_ difficult.

It is the opposite of intuitively extraordinarily difficult. It is much easier and more intuitive than understanding code. It is, however, different from code, so your coding skill do not automatically transfer to TLA+, but developers are generally able not only to read but to write TLA+ specifications of complex systems after a 3-day workshop or about 2 weeks of part-time self-study. Learning TLA+ is far easier than learning a new programming language, and it is much simpler than any programming language in existence. The difficulty is not at all with intuition, but with unfamiliarity. In any event, reading TLA+ is much, much, much easier than writing/understanding the systems for which you use TLA+ for.

Post reply on HN