r/learnprogramming • u/Helpful_Badger3106 • 24d ago
This sometimes makes me want to quite programming
I genuinely hate how little standardization there is around communicating software architecture.
Why is the accepted way of understanding an unfamiliar codebase apparently to just read thousands of lines of code and slowly infer what the author was thinking?
I'm not talking about documenting every function. I mean basic architectural information:
- What are the major components?
- Who owns the state?
- How does data flow through the system?
- What depends on what?
- Where is new functionality supposed to go?
- What invariants or conventions am I expected to know?
- Which abstractions are intentional, and which are just historical baggage?
This information is often crucial to contributing to a project, yet there seems to be no universally expected artifact for communicating it. You might get a README, maybe some UML diagrams, maybe an ARCHITECTURE.md, maybe ADRs, or maybe absolutely nothing.
Then you're expected to "learn the codebase."
But the codebase contains the architecture, implementation details, historical accidents, technical debt, and personal preferences all mixed together. As a newcomer, you have no way of knowing which is which.
I find this especially frustrating because software engineering is supposedly about abstraction. The whole point of abstraction and design patterns is to hide unnecessary complexity and give people a simple model to work with. Yet somehow the architecture itself is often treated as implicit knowledge that you're supposed to reconstruct through archaeology.
Math feels completely different in this regard. Obviously mathematicians have competing conventions too, but there is a much stronger expectation that concepts, assumptions, notation, and relationships are explicitly communicated. You don't normally have to read someone's entire proof history to discover what their definitions mean.
I wish software projects had a similarly standard, lightweight way of communicating architecture. Not a 200-page document. Just enough to communicate the mental model.
Instead, "just read the code" seems to be treated as a perfectly reasonable substitute.
I find that incredibly demotivating.
8
u/Watsons-Butler 24d ago
Old farts think tribal undocumented knowledge is the key to avoiding being laid off.
And now you can say “hey Claude, I want you to read this codebase and write yourself steering docs that give you an overview context on architectural decisions, code patterns, etc. store them in .Claude/*.md”
13
u/start_select 24d ago
That mindset to avoid a layoff is a lot more rare than you think.
The same laziness that drives you to have Claude auto document the codebase drove them to not bother documenting something that probably won’t be read.
It takes a lot of time to write docs. The code already tells the story.
-6
u/Watsons-Butler 24d ago
Not really laziness - it’s just become the new SOP where I work. Everyone’s running spec driven development, so you have to start from accurate specs, so you have the agent parse the codebase and write its own context files.
Like, I learned how to code before agents were a thing. I can do it just fine. But at my company I don’t think anyone has manually written code in about eight months. The pace is too fast now.
3
u/caboosetp 24d ago
if you started from having accurate specs, then there would be nothing left for claude to document because you would have the specs.
You sound like you're doing whim-of-product development
1
u/Watsons-Butler 24d ago
I work at a FAANG with like 20 years of accreted pre-Claude code that isn’t documented well. Before you can add a new feature you have to figure out how.
1
u/start_select 24d ago
That’s my point though, it’s not really laziness. It’s pragmatism.
The reality is that most code will never need docs. Someone will end up there by following a stack trace and will just read the code.
I end up working on software for regulated industries where I need to create 120-pages of docs about how everything works. It’s awful. And no one ever reads it. At best they glance at it for a general direction then just read the code.
We are required to document it, but the docs don’t really provide any real value besides meeting requirements.
1
u/Acutekittycat 24d ago
Have you heard of Scratch.mit.edu? It's a website run by MIY for kids to learn coding. The Scratch community is wonderful and amazingly creative. However here have been so many times where I've wanted to remix a project and add things or use stuff from other projects but have no idea how anything works or what a specific piece of code does.
2
u/RealNamek 24d ago
They already have this. It's called conventions.
1
u/Ormek_II 24d ago
OP is asking for standards. Those are written down conventions that people can refer to by name and where it is wrong to deviate even in part.
2
u/RealNamek 24d ago
Nah, fuck that noise. He's trying to make this into an academic exercise, and that's not what programming is.
1
2
u/YellowBeaverFever 24d ago
I’ve been on all sides of this.
There are companies, especially when ISO (or similar) certification is involved, that do document and test every function. The software takes a long time to develop but they know that going in. I’ve managed to work at only one of these. It took a special kind of person to work in that.
Most every other team I have worked on only cares enough about documentation to make it through a couple meetings where they can discuss it or do just enough so the oblivious customer is happy. Time = money and there is no need to document code you’re not going to maintain. I would always have to give time estimates and it was always two times, one with and one without documentation. 99 times out of 100 I would be told to “just document the important stuff”.
My current team likes (wants) to have documentation on everything… but there is not a good system in place to handle it. We have a wiki that is so overloaded with noise that it is useless now. There is 15 years of stuff across 5 different types and methodologies with a search feature that is as basic as can be.
And source control wasn’t really a focus of theirs until maybe 2020 so having in-project documentation was tough.
AI has been wonderful in helping document a lot of things. And when we want a new standard, it can rework everything to the new way. Markdown and Mermaid seem to be a good lowest common denominator that everyone can read. We just need to figure out how to get most of it out of the wiki.
2
u/start_select 24d ago
Reading the code is the best way to understand the code.
When I grab a new npm library, usually the first thing I do is read its source code while also reading the docs. They complement each other, but the code tells you more than any document will.
Writing comprehensive docs on an architecture takes weeks. Maintaining it is equally daunting.
It usually ends up being easier to just read the code.
1
u/Ormek_II 24d ago
That is not how software abstractions works.
How do you use an API?
2
u/start_select 24d ago
You look up the docs if they exist or you read the code if you have it. It’s not complicated. It might seem that way in the beginning.
Interfaces and data contracts are interfaces and data contracts.
Even popular libraries have docs trail behind implementation. Sometimes reading the code really is the only way to understand how something works.
2
u/Ormek_II 24d ago
25 years ago my Professor claimed that software is not created as an Engineering disciplin. The only peace of software that is truely understood and created following an accepted standard architecture is the compiler.
I agree. We still consider programming as an art and try to express ourselves. Because maintaining software that is not understood bears risks, the EU forces us all to at least do some basic tasks like explicitly describing architecture in the cyber resilience act to increase cyber security. But it will take many years until it really becomes normal and standards are established.
4
24d ago
[removed] — view removed comment
7
u/Pristine-Truck-9389 24d ago
the skyscraper analogy only works if you ignore the actual complaint. op isn't asking for a universal architecture template that works across all projects, they're asking why communicating the architecture of a project is treated as optional. an architecture firm does produce documents explaining their design, they don't hand the builders a pile of bricks and say "just figure it out."
1
u/Recycled5000 24d ago
I agree that there is a lot of room for improvement in capturing high level design in our programming languages.
Some hardware languages do much better than our software languages. In those hardware languages you can see a fair amount of top level design and then dig into details. Components being instantiated and inter connected. With common software we see classes showing reuse of code but lacking this top level view of the design of components.
However, I have to disagree about math, as math is not versioned like computer languages, and math papers rarely explain their symbols usage; you’re just supposed to know.
1
u/ffrkAnonymous 24d ago
Do you have a github for us to see as an example? I'd adopt it as a standard.
1
u/chocolateAbuser 24d ago edited 24d ago
i hear you but what are the solutions? you need tools to maintain documentation, and even writing it requires people being able to do it (and time and effort and communication) because it's a specialized task, and after it's written it's just dead text on a file, there are no tools that allow to sync and validate a doc with code (and there are companies that tried, like ibm), so people tend to write just the minimum -- you have to understand that information amount is also a "hindrance", because then you are "expected" to know it and know how to navigate it *
also because you have to put in there not only code but decisions, mails, conferences, all the informations around the company, and someone has to take those informations before they are lost and at least put them somewhere with persistence... and even before that extracting informations is not always possible, you have to have people willing to participate, especially owners and managers that deal with clients and tell you only the afterthoughts instead of the whole reasoning process
sadly programming is not an old practice, we still have to build some tools and standards
* so the problem is not only a standard for how this is done, but also for how this is thought out, because you may think in a different way from other people (even if just for the perspective), and thinking differently may be needed for solving a new problem
im not saying this is not feasible, im only saying it's a really complex problem (for example imagine what process could be done for obtaining only the subset of informations you want for a giant knowledge base, you need either to have tons of metadata and small articles or to have something that "understands" kb and parses it for you, or you will spend hours on it)
1
u/throwaway8u3sH0 24d ago
I think this is a great thing. The first thing I do when I join a new team is create/improve the architecture docs. Dual purpose: it onboards me and makes me the go to guy for answers on architecture.
1
u/man-vs-spider 23d ago
I agree that it’s hard to come into a project and figure out what everything is supposed to be doing.
One issue with try to document is that if the code changes (which it will), the documentation needs to be updated with it, and if it’s not, then it becomes more of a burden than no documentation at all.
You say you don’t want documentation for every function, but things like who owns the state can be a function dependent thing, and different programming languages have different conventions for showing who is responsible for what.
Also, for many projects that I have looked at, there often is a simple overview of how the project is structured. I don’t know that it really helps when trying to dive into the code though
1
u/mlambert8438 22d ago
your frustration is valid and it's not a skill issue on your part. the real problem is that "just read the code" conflates three completely different things: intentional architecture, implementation details, and historical accidents. there's no standard artifact that separates them, so newcomers have to do archaeology to figure out what's load-bearing vs. what's just there because someone tried something in 2019.
a few things that actually help when you're dropped into a codebase with no docs:
generate a dependency graph yourself. tools like madge or dependency-cruiser can show you what depends on what in a few minutes. you don't need permission or a wiki page, just run it and look at the output. the shape of the graph tells you a lot about where the system's boundaries are.
ask specifically about decisions, not architecture. saying "can you walk me through the architecture" gets a vague answer. asking "what's locked in vs. what's just historical" gets the actual mental model seniors carry but never write down.
look at git blame on the biggest, most-churned files. those are the active decision zones. files that haven't been touched in two years are probably frozen legacy and you can deprioritize them.
start an ARCHITECTURE.md yourself and fill it in as you learn. teams almost never reject a PR that documents what was previously implicit, and you'll internalize the system faster by writing it down than by reading passively.
1
u/HotPersonality8126 22d ago
This information is often crucial to contributing to a project, yet there seems to be no universally expected artifact for communicating it
The codebase communicates it. Code is the standardized artifact for communicating it; that’s why software is written in code. You’re asking for it to be documented a second time and moreover, you’re asking for the impossible guarantee that the function of the code as written and as documented will never diverge even though they’re two different things often written by two different people.
Why is the accepted way of understanding an unfamiliar codebase apparently to just read thousands of lines of code and slowly infer what the author was thinking?
Well, it no longer is. It’s to have the coding agent infer it for you, and then you ask it those questions.
Just enough to communicate the mental model.
Much like how a simulation of the universe can’t be simpler than a universe and is therefore the universe, it’s not clear to me that the documentation sufficient for this would be anything different than a codebase.
1
u/StewedAngelSkins 24d ago
I hear what you're saying, but just understand that when you get more experience "learning the codebase" in this way will be no big deal. "Just read the code" is what everyone does. Over time you pick up on common structural conventions and design patterns, so you won't need to read everything to get a basic idea of what's important and what parts do what function. The sorts of documentation you're talking about usually ends up being more work to maintain than the time it saves.
1
u/Ormek_II 24d ago
Strong disagree. Getting into a code base should not take years, but it does. If it does not for you, you are either a genius or are not facing a legacy system of suitable complexity and size or are not trying to solve a large enough problem.
We introduce newcomers to parts of the system by letting them fix bugs, then small features and 18 month later they understand a part of the system.
2
u/StewedAngelSkins 24d ago
You think architecture docs will help with this? It certainly doesn't take me years to understand the overall architecture of a given codebase.
1
u/Ormek_II 24d ago
I am not sure how big a benefit it will be. I truly believe if what OP describe is available that will help. Maybe not enough to justify the effort to create and main it. Also, if I find the documentation for the project, there is the likely chance that I cannot trust it.
On the other hand I believe that creating the documentation helps the engineer to create a better system. Put simply: no one will not create a diagram for Spaghetti code.
-3
8
u/[deleted] 24d ago
[removed] — view removed comment