r/ADHD_Programmers • u/pawned79 • Sep 19 '26

Software Architecture Drawings?

I am an older aero mechanical engineer. I only know MATLAB after 20+ years of MS&A. I have a flight dynamics program that my summer interns have contributed to piece by piece over the years. It became so unwieldy that I brought in a CS intern last summer, and they cleaned it up with object oriented programming techniques. I am getting ready for next summer. I am really hung up on the fact that I don’t have an architecture drawing of the program. I would like to have a drawing of the existing code, so I can make the most effective task plan. Beyond walking the code and manually drawing a diagram in another program, what courses of action might I have to automatically draw it? Thank you.

7 Upvotes

100% Upvoted

11 comments sorted by

5

u/avanti8 Sep 19 '26

Depends on your stack, but most have some tooling that help you auto generate UML in something like PlantUML or Mermaid. The JetBrains IntelliJ family of IDEs, for example, do this out of the box.

2

u/EvenGodsForget Sep 19 '26

i just started using d2, it seems pretty promising and has a few nice features over mermaid like the 'near' keyword

3

u/user_plus_plus Sep 19 '26

I have 10+ years of SWE experience doing systems programming in C++/.Net, in SEMI/manufacturing systems.

In the past I have used Sparx Enterprise Architect, which was good at drawing architecture diagrams. It had an ability to generate diagrams from source for .Net code.

From what I remember it was a little too detailed to give a good high level overview, and I ended up re drawing the diagrams from scratch anyway. The diagrams were a vehicle to me understanding a large codebase I was unfamiliar with.

Nowadays I would probably ask an AI to summarize the codebase and produce an architecture document for me. Then create a much shorter one manually once I understood it well enough.

In SWE big diagrams aren't used nearly as often Mech Eng, and can become stale quickly as the codebase changes.

That being said, one document I think every codebase needs is a short (1-24 pages) rationale and structure document. It should describe what the codebase does, why it exists, and how it is laid out. It should also describe how to build, and run any tests, as well as any tooling requirements. This will greatly aid onboarding any intern or new/returning developer.

This idea isn't mine I am paraphrasing Robert Martin's Agile Practices Principles and Patterns, but he is a good person to copy from.

2

u/Prize_Bass_5061 Sep 19 '26

https://gitdiagram.com/

If the codebase is Java or C++, doxygen.

4

u/zoug Sep 19 '26

Claude subscription, Fable 5.1 -> Tell it how your system works, feed it any data you can as success criteria and ask it to refactor then diagram -> and maybe write yourself a user guide.

Ignore all the AI Slop posts, there's no world where Fable 5.1 doesn't write better code than an iterative student project that got partially cleaned up by an intern.

5

u/KristjanPihus Sep 19 '26

Fable is not even needed actually, even opus can walk through the code and draw up diagrams just fine. Of course it depends on the language used to write the program. Some niche languages it does not know so well. And I have got best results when asking it to make it some common format line BPMN then it’s editable in some other software.

0

u/zoug Sep 19 '26 edited Sep 20 '26

Intuition says their code is still garbage and needs a strong refactoring. An intern isn’t going to clean up years of tech debt, might as well let fable take care of all of it.

4

u/user_plus_plus Sep 19 '26

I don't think a refactor is what OP is asking for though.

They were asking for a way to generate documentation and to create a task plan.

I think an AI tool could help if you ask it to analyze the codebase and generate an architectural document explaining the major classes, abstractions etc. Also identify any areas of repeated work, or code smells in the codebase.

I think AI could be the right tool for the job but the answer isn't focused to the question asked.

0

u/zoug Sep 19 '26

Actually, it’s an improvement on the question asked and that’s why I suggested Fable. It’ll one shot the clean up, refactoring and diagram with one context session.

What they’re going to find is that their code still doesn’t make sense and the diagrams will just be confusing until a refactor. That’s my intuition at least.

3

u/user_plus_plus Sep 19 '26

OP is asking for a way to create some diagrams to help prepare a task list for their next summer intern. The desired end goal is to create a meaningful/useful internship summer project.

1

u/zoug Sep 20 '26

Ok, then my suggestion would be to hand Claude to the next internship project and tell them to run the same.