I remember having the same problem earlier in my career. I inherited a code base that was a million lines of code and 15 years old. Things I tried: printed out the nastiest 2000 line function on a giant piece of paper, logged every function entry. Things that worked well at the time: reading filtered logs of actual code execution, tracing through code to see how it works. What I would do if I could talk to me 10 years ago: Don't worry about the big picture. Trace through the code path relevant to your task and make sure you understand whatever inputs/outputs there are on that path. If there's something that makes 0 sense, ask a senior dev. After tracing through enough paths, you'll start to develop a mental map, in the same way you develop a mental map of a geographical location, after visiting about five locations in the same area. You get to know the main roads, highways, etc. You have a knowledge of the relevant paths; you don't always need a map of the whole city.
Ask HN: Visualizing software designs, especially of large systems (if at all)?
101–110 of 129 posts
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#102> ...documenting the code design...
I would say that code is an implementation of (part of) a design, and both implementation and design should be documented appropriately.
If it's not present, make as much text and visualizations you need for you to understand it. As you are a developer start with the code. I prefer C4 over UML for the separation of contexts. Good and fun exercise!
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#103If you're interested in diagramming system architecture in a top-down fashion, I'll pile on another recommendation to check out the C4 model[0].
As others have mentioned, to effectively communicate a system you must limit the context to particular layers of abstraction, and C4 is a good approach to doing just that. There's also a C4 plugin for PlantUML[1].
But don't forget that, as with all visualizations, audience and purpose are key.
Consider whether you are addressing short-term needs (eg identifying inefficiencies, modeling for a client pitch) or long-term needs (eg knowledge retention, managing complexity). If your audience's needs are short-term, you can certainly get by with much simpler tools (eg Inkscape, excalidraw/draw.io/etc, picture of a whiteboard, doodles on a napkin).
Also consider whether or not you actually have a problem better served by bottom-up (ie generated) visualizations (eg ERDs for database schema refactoring, heatmaps for profiling, GraphViz for debugging DAGs).
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#104Interfaces. A well designed system will present simple interfaces with clear delineations of responsibility. All elements will be carefully named to minimize the potential for confusion or misuse. In such a system, diagrams become not only easy but semantically meaningful. Programmers use this to manage complexity, and in business domains laypeople should usually also be able to comprehend the chosen abstractions.
To describe messages and related state transitions representing the function of a system over time, numbered arrows atop a block diagram can work well (essentially one visualization of a graph), but for more complex multi-component interfaces with a strong requirement for ordered messaging, message sequence charts are well received. https://www.mcternan.me.uk/mscgen/
There are two models of reality that I find to be the most useful ones, especially when writing programs. The first is functions, and the second is sequences of states. - Leslie Lamport
.. via https://github.com/globalcitizen/taoup - see also https://en.wikipedia.org/wiki/State_machine - and you won't regret learning http://graphviz.org/
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#105For a small but complicated project I got thrown into a while ago, the only way for me to understand it was to print out all the source directly, vertically tape together the pages for a single file, and then lay them all out on a huge table. Then I took multicolored markers and started physically drawing out the call chains. I then I sers-toi the system, and also found an enraging bug: the system widely used the var…
I use pen and paper as well, but rather than print out all the source code, I write down the call stack. A calls B calls C, etc. along with the line numbers of the call. Much easier than printing out the source and you still have the IDE niceties like go to definition, find in source, etc.
Hah! I did the exact same thing for ages on paper and eventually evolved the system to manage my workload and context switching… I still use it a lot for going deep while debugging/understanding code. I ended up making it into an app when I broke my wrist and could still type but couldn’t hold a pen. I can’t remember if there’s rules about self promotion in comments here but it’s up at journalist mode dot com
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#106I’ve tried c4/plantuml (and loved the concept) but have never been able to make it stick, it always seems to get out of date quickly and having a feeling of “I’m not sure if this is up to date” is worse than no documentation at all (because you need to learn the documentation, then the behaviour). Honestly the fastest way I’ve found to understand large distributed systems is by observing the interactions between them, schema detection in service bus type architecture and tools like X-ray (in aws) or open tracing give you a good picture of “this thing produces or consumes this type of message”
For individual systems I think a good inversion of control/dependency injection system can give you a good overview of the connections between components.
If I’m stepping into a giant ball of spaghetti code I generally set the debugger at line 1 and start stepping, and draw a lot of boxes and lines as I go… then throw those drawings away when I’m done. They’re really only helpful while you’re producing them (like taking notes as you read a textbook), hopefully in that situation you improve the code as you go so this approach isn’t as necessary!
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#107For a small but complicated project I got thrown into a while ago, the only way for me to understand it was to print out all the source directly, vertically tape together the pages for a single file, and then lay them all out on a huge table. Then I took multicolored markers and started physically drawing out the call chains. I then I sers-toi the system, and also found an enraging bug: the system widely used the var…
First principles! I've totally done this. Especially in a large pub/sub oriented frontend codebase where it's really hard to map out where any given data could have come from
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#108Recently stumbled upon [C4 Model](https://www.youtube.com/watch?v=x2-rSnhpw0g), which seemed very promising. It builds on the failure of adopton of UMLs, and aim to be practical and communicative.
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#109For a small but complicated project I got thrown into a while ago, the only way for me to understand it was to print out all the source directly, vertically tape together the pages for a single file, and then lay them all out on a huge table. Then I took multicolored markers and started physically drawing out the call chains. I then I sers-toi the system, and also found an enraging bug: the system widely used the var…
Language support varies but if it’s possible, why not generate an AST and count references, bubble up most common, etc?
Could do similar with bash text mangling tools, but language native would probably be best.
I dunno, just a thought in an EOD fog. I don’t own a printer these days, so I guess I’d need an alternative.
Tell computer to observe self and report back.
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#110I typically see data flow, data model, and sequence diagrams.
Keep them small, if you need more than 7ish boxes, your model is too detailed