[deleted]
Ask HN: Is there a better way to document complex software architectures?
111–120 of 239 posts
Re: Ask HN: Is there a better way to document complex software architectures?
#112Earlier quoted context omitted.
Sometimes the least complicated architecture is still complicated (by human standards).
What i mean is, the simplicity is in the: "If i cameback to my project after 1 or 2 years, i can easily work with it because it has no complexity to remember".
Some problems are inherently complicated, even if you come up with the best design.
Re: Ask HN: Is there a better way to document complex software architectures?
#113“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
That's scary to even read
Re: Ask HN: Is there a better way to document complex software architectures?
#114Quick 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.
Ditto, except that I have 30 years professional experience.
Re: Ask HN: Is there a better way to document complex software architectures?
#115Full 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.
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.
Re: Ask HN: Is there a better way to document complex software architectures?
#116“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
Looks like a schema to allow the code to decide the real schema at runtime. A poor mans mongodb.
Re: Ask HN: Is there a better way to document complex software architectures?
#117This is a loaded question. Is there a better way? Maybe. It is almost certainly not any easier, though. Likely takes longer and requires as much investment from the reviewers as it does from the authors. I confess I'm fond of Literate Programming for this, though, I have never tried introducing it in a company. My hunch is it would take too long. By far. Even documented software often takes too long. Same reason you…
I've long dremead of a architecture view that was zoomable, zooming in enough would end up on the actual code, but zooming out a lot would show you app server +database basically.
Re: Ask HN: Is there a better way to document complex software architectures?
#118> where is the modern 'IDE' for the Software Architect?
Generally architecture is about imposing constraints on the system. If you think about it that way, what you really want is not to be treating Visio and PowerPoint documents as the primary artifacts. You want to define the modules (in Parnas's sense) and their interfaces and executable specifications. You want tooling that lets you constrain what modules may use other modules, automatically test modules, automatically mock modules, and be alerted when the constraints are broken.
Now, most of the tooling for this probably doesn't exist, or exists in partial, widely scattered forms. For example, you can define a Java package with the interfaces of a module and then have some kind of hook in the build system that checks that it is not being imported in places it shouldn't be. You can mark the interfaces that should be considered architectural constraints with a custom annotation and build a tool to extract out all uses of them and plot connections.
But I am unaware of any toolkit that will do what you want.
Re: Ask HN: Is there a better way to document complex software architectures?
#119>where is the modern 'IDE' for the Software Architect It's the same one the software developers use, 'architects' don't stop coding, the system architecture doesn't exist in Visio or PP. It's evident from the structure of the codebase and the accompanying documentation, your role is to collaborate and work with the senior devs to ensure this design vision is realised and to explain in documentation why this architect…
The Ballerina programming language (ballerina.io) has a syntax designed in such a way that any syntactically correct program can have its sequence diagram generated automatically. It's a type of self-documenting programming language. It only documents for the scope of the service that is being programmed, but eventually if many components and services are programmed with Ballerina, system wide architecture diagrams c…
I wonder if this needs its own language. It looks like c# from a quick glance. I wonder if static analysis on an existing language would be just as good. In any case I love this idea.
Re: Ask HN: Is there a better way to document complex software architectures?
#120Gaphor ( https://github.com/gaphor/gaphor ) is an open source UML tool written in Python. The goal is to create a simple, easy to use modeling tool not a big enterprise tool like the ones already mentioned. I would like to soon support SysML which is for modeling systems design and requirements. We are finishing up converting it to Python3 and Gtk+3 now. We would love more involvement or input if there are things you…
Side remark: A few screenshots and/or video would be a great intro to get a feel of the program