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

201–210 of 239 posts

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

#201

Post by ako »

zeroname wrote: post #181
pojzon wrote: post #168

Earlier quoted context omitted.

"WORKING PRODUCT, over comprehensive documentation" Software changes too fast to make a static snapshot of it. Its the same with comments in the code, few months later what was there is no longer valid and only creates confusion. But i can understand managers dont like that because it makes it harder to replace ppl.

> Software changes too fast to make a static snapshot of it. Architectures don't really change that fast or often, except maybe in the initial phase. That's why most UML diagrams are a waste, they are concerned with low-level details like classes or internal interfaces.

Agreed, the architecture diagrams I usually look for are high level, mostly about how different systems are connected. These don't change that much.

When looking at architecture diagrams, usually you don't want them lower level details anyway, they would just obscure the big picture.

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

#202

Post by AngeloAnolin »

I only abide with one rule - the documentation that you would create, whether diagrams, contextual model, or any artifact related to the software should be something worthwhile to read. Otherwise, it all becomes a meaningful assumption with zero audience.

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

#203

Post by ace_of_spades »

I have been a little out of the game lately but I remember that things like ArchiMate [1] try to solve or at least improve your situation. But this may very well be out of date. There is some research into improving IT architecture management going on all the time.

1: https://www.archimatetool.com/

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

#204

Post by sjellis »

avip wrote: post #91
cubano wrote: post #87

Quick question that I only ask because of my 30-odd year history as a corporate contractor... Does anyone here really use those UML-based docs to actually learn the systems? Or do they do what I always did and use the trusty step-debugger for a few days and come up with your own mental model of them? Inevitably, unless someone is working full time on them, they are incomplete and several months out-of-date, and that…

It's pretty straightforward - if it's pdf it's not versioned. If it's not versioned it's a fossil. The only thing I've ever done to reason about a new system is read the tests.

These days I preach the gospel of the project README: One file, Markdown format, versioned with the code, that says what the project does with high-level concepts, and how to build it and run the tests.

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

#205

Post by DomreiRoam »

cubano wrote: post #87

Quick question that I only ask because of my 30-odd year history as a corporate contractor... Does anyone here really use those UML-based docs to actually learn the systems? Or do they do what I always did and use the trusty step-debugger for a few days and come up with your own mental model of them? Inevitably, unless someone is working full time on them, they are incomplete and several months out-of-date, and that…

I worked on a project that needed to implement regulations specified in legal documents. An analyst did work on reading hundreds of pages of legislation to extract UML diagram representing the objects and their relation sand also all constrains defined by the legislation. In this case, it was quite useful to have UML as an intermediary and not force developers to be jurist. The UML documentation was checked and validated by expert of the domain.

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

#206

Post by enimodas »

josephg wrote: post #193
CMCDragonkai wrote: post #176

Earlier quoted context omitted.

The database was meant to be the CMS and SQL was designed to be human readable.

Counterpoint: If small design decisions require global SQL schema changes, it slows you down. And small barriers to change will, in aggregate, kill you. Eg, over a month of iterations: "Can we add another field to user registration? It should be free text. Oh, they should select from a list. No wait, make it a date. Actually a date and a text field. No wait, dump the text field." Sometimes slowing down these changes…

Sounds like the real problem is that there's too much friction with schema migrations.

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

#207

Post by taeric »

vruiz wrote: post #157
taeric wrote: post #52

Earlier quoted context omitted.

If the code is generated from the diagrams, why check the code in at all? Feels akin to checking in the bytecode with your the java that generated it.

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.

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

#208

Post by taeric »

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.

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.

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

#209

Post by taeric »

rocqua wrote: post #115
taeric wrote: post #52

Earlier quoted context omitted.

If the code is generated from the diagrams, why check the code in at all? Feels akin to checking in the bytecode with your the java that generated it.

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.

Neither of those seem like compelling reasons, though. If the code isn't good enough, you are better incentivizing the team to improve the tool's generated code, than you are increasing the drift between what the tool generates and what is used.

Optimization can almost make sense, but maintaining a patch process is almost certainly the superior way to go. If only because it supports staying current on the generated code.

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

#210

Post by jonathanlydall »

taeric wrote: post #52
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…

If the code is generated from the diagrams, why check the code in at all? Feels akin to checking in the bytecode with your the java that generated it.

The main reason is that our "code management" (essentially code weaving) system allows coders to painlessly mix their own custom code in the same file as generated code.

This is very useful for cases where you want to model signatures of methods in our tool, but then leave it to the developer to implement the method which performs the business code. If you want to change the signature of the method, for example adding a parameter, then our code generation will add it in without messing up your custom code.

Our own templates generate code which is as beautiful looking and readable as code written by the best developers, and we encourage template writers to do the same. This makes working with the code in your IDE and reading it as much of a pleasure as any other well written code, having it in your SCM also gives you a history of how the code has changed over time.

Finally, use of the tool is optional, if you hand the the repository over to another team, or as a contracter you deliver it to a client, they don't need the tool, and just get code which looks as if it was written by a good developer.

Post reply on HN