3 ms·

Speculating based on both writing large systems from scratch, and joining a group where a large confusing system was being used... Diagrams are sometimes unnec

by dahart 4y ago

Speculating based on both writing large systems from scratch, and joining a group where a large confusing system was being used... Diagrams are sometimes unnecessary overhead early in a project. Sometimes I’ve used them and seen other people use them for initial design planning, especially if management needs to be involved or approve the plans & schedule. But by a year later, the design has grown and changed, and everyone on board is so familiar with the code, but also so pressed for time and feature delivery, that making diagrams doesn’t make sense: nobody involved at this point needs them. Two years later, when the code is getting complicated and slowing down, and you’re onboarding some new people, that’s when it might help to sketch the flow of code. FWIW, sometimes a good profiling tool will show you and let you explore call stacks, call graphs, execution charts, etc. I often reach for a profiler when I’m new to a codebase. Flame charts are a fave of mine. You can find flame charts in Chrome’s debug tools, or in compiled language profilers like vtune or valgrind. Here’s a decent article on how to use them https://www.brendangregg.com/FlameGraphs/cpuflamegraphs.html https://www.brendangregg.com/FlameGraphs/cpuflamegraphs.html Another issue is that well designed code bases diagram themselves by their module structure, while diagrams for poorly designed code bases may not help understand them at all. When code has too many side effects, or things are poorly or misleadingly named, when class boundaries aren’t well defined or the code has a lot of spaghetti, diagrams might not really help. IMO two things worth doing are: get a mentor in any new codebase any time you can, and 2) start building your own arsenal of code diagramming tools, rather than wondering why or waiting for others to do it. Demonstrate the value of diagramming code to people around you and see if you can get it to catch on.

lurker137 4y ago
The thing with profiling tools is that they're more focused on the details than the big picture at the system level. I'll definitely be using flame graphs more though, thanks for the tip. Also you are absolutely right about waiting for others to make the tools, but sometimes the tools don't exist for a good reason that I wouldn't have realized otherwise.
- dahart 4y ago
  Yep, that’s totally true. Profiling & debugging tools are designed for sampling the behavior and performance, and not primarily for understanding architecture. Still, they’re great for inspecting call stacks, which can be pretty damn helpful for certain parts of understanding the code. IMO there’s no real substitute for getting the design explained by the people who designed it. (Of course this isn’t always possible, but when it is, take advantage.) Automated tools can never prioritize the explanation nor summarize what parts are critical or tricky vs what parts are incidental or trivial, and they can’t tell you which parts should be redesigned because they were slapdash vs which parts look ugly to a newbie but have a long list of hard to see requirements, and touching things should be done with extreme care. Good diagrams are very helpful, but best used as a supplement to in-person stories, in my opinion.

by dahart 4y ago

lurker137 4y ago

The thing with profiling tools is that they're more focused on the details than the big picture at the system level. I'll definitely be using flame graphs more though, thanks for the tip. Also you are absolutely right about waiting for others to make the tools, but sometimes the tools don't exist for a good reason that I wouldn't have realized otherwise.

dahart 4y ago
Yep, that’s totally true. Profiling & debugging tools are designed for sampling the behavior and performance, and not primarily for understanding architecture. Still, they’re great for inspecting call stacks, which can be pretty damn helpful for certain parts of understanding the code. IMO there’s no real substitute for getting the design explained by the people who designed it. (Of course this isn’t always possible, but when it is, take advantage.) Automated tools can never prioritize the explanation nor summarize what parts are critical or tricky vs what parts are incidental or trivial, and they can’t tell you which parts should be redesigned because they were slapdash vs which parts look ugly to a newbie but have a long list of hard to see requirements, and touching things should be done with extreme care. Good diagrams are very helpful, but best used as a supplement to in-person stories, in my opinion.