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

171–180 of 239 posts

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

#171

Post by zanny »

henrik_w wrote: post #96
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've been developing software professionally for 25 years. I've never found them to be useful. Even if you have them, they're usually out of date, and anyway they don't really help answering the questions you have. None of the places I have worked at have put a lot of emphasis on UML diagrams.

What would be useful is the ability to generate diagrams like UML from an AST. I'm sure theres already a Rust crate for it out there somewhere...

Then it could just be the case where you pick out a root struct / mod / something and a depth and let the software generate you a pretty graph to stick on a slide for the meeting in 15.

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

#172

Post by agentultra »

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…

For some of the Amazon engineers mentioned in the paper that training took 1 to 2 weeks.

The trade off for that training is that you know the those properties it describes are correct. For some systems the trade off is worth it and for a few, required.

I didn’t say you should use TLA+ for simple projects. It is incredibly useful for specifying systems where correctness, liveness, etc matter greatly and the complexity of the project is sufficiently high that you’d be uncomfortable describing it with boxes and arrows.

I think it’s rather reckless to design a complex system of the sky-scraper magnitude without some sort of verification tool like TLA+.

It’s a matter of degrees.

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

#173

Post by danmaz74 »

I personally found that the most useful diagram to help me understand a Rails project I don't know is the E/R automatically generated from this tool: https://github.com/voormedia/rails-erd

Being automatically generated, it's always up to date. As many others noted, I never had luck with written docs because it never happened to me to find good ones which were in sync with the project.

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

#174

Post by bluGill »

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 have. When they are up to date they are useful and easy. There is only one time I've seem them up to date: the UML was used to generate the headers (we used C++ at the time).

If the build process doesn't force the UML to be kept up to date, then you should only do white board uml: draw the diagrams on a whiteboard, and erase the whiteboard two weeks latter.

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

#175

Post by Aeolun »

platz wrote: post #99
zzzzzzzza wrote: post #2

“Show me your flowcharts (source code), and conceal your tables (domain model), and I shall continue to be mystified; show me your tables (domain model) and I won’t usually need your flowcharts (source code): they’ll be obvious.” ~ Fred Brooks, “The Mythical Man Month” Stuff that has improved or the potential to improve the documentability of modern systems, imo: postgREST, custom types (e.g. domains in postgresql),…

But my domain model is Store ===== Id int Col1 varchar Col2 varchar Col3 varchar ... Col134 varchar foreignKey1 varchar foreignKey1Type varchar foreignKey2 varchar foreignKey2Type varchar ... foreignKey10 varchar foreignKey10Type varchar validFrom varchar validTo varchar isActive boolean deleted boolean

Ah, it’s good they used varchar, at least now you can store everything in those columns.

And there’s a multitude of ways to soft-delete too!

This is much better than some schemas I’ve seen.

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

#176

Post by CMCDragonkai »

rco8786 wrote: post #136
quickthrower2 wrote: post #116

Earlier quoted context omitted.

Looks like a schema to allow the code to decide the real schema at runtime. A poor mans mongodb.

This is pretty common looking for things like CRMs or CMSes where customer specific custom fields rule the day.

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

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

#177

Post by muthdra »

Aeolun wrote: post #175
platz wrote: post #99

Earlier quoted context omitted.

But my domain model is Store ===== Id int Col1 varchar Col2 varchar Col3 varchar ... Col134 varchar foreignKey1 varchar foreignKey1Type varchar foreignKey2 varchar foreignKey2Type varchar ... foreignKey10 varchar foreignKey10Type varchar validFrom varchar validTo varchar isActive boolean deleted boolean

Ah, it’s good they used varchar, at least now you can store everything in those columns. And there’s a multitude of ways to soft-delete too! This is much better than some schemas I’ve seen.

Not 2 years ago, I saw an entire Joomla schema converted to Microsoft Excel tables which we should use to port the website. Our team just ignored the effort.

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

#178

Post by thrower123 »

muthdra wrote: post #177
Aeolun wrote: post #175

Earlier quoted context omitted.

Ah, it’s good they used varchar, at least now you can store everything in those columns. And there’s a multitude of ways to soft-delete too! This is much better than some schemas I’ve seen.

Not 2 years ago, I saw an entire Joomla schema converted to Microsoft Excel tables which we should use to port the website. Our team just ignored the effort.

Probably the most important part of that effort was to keep the project managers and analysts busy fighting over that nonsense, providing aircover for the devs to actually do the work.
Post reply on HN