Title is a bit overblown for the actual epiphany which is more about the necessity of programmers having a robust mental model of a system to be able to maintain, let alone improve the system. I don't see anything particularly unique to software in this thesis, as complex physical systems also have the same characteristic.
I also think this is way off base:
> It means that the code base we create is not the true product of our work. The real product is the mental theory of that code base which
This is manifestly not the case. The value of computers is that you can write code once, and the computer can execute it repeatedly ad infinitum. As a programmer, your mental theory of the code base has value to its owners, but it's not the product. The code base is also not the product. The product is whatever output is created and consumed by the relevant stakeholders.
> As a programmer, your mental theory of the code base has value to its owners, but it's not the product
If you lost all of the code today, with the right understanding you could build it again relatively quickly. If you lost all that understanding, say all the developers quit, the program will no longer be adapted to customer needs potentially for years until that understanding is rebuilt.
I agree that "product" is probably not the right word, probably "asset" fits better. Losing that knowledge is like losing a manufacturing plant for your product. The plant isn't the product but it's a key asset for producing the product.
At a micro level, this helps articulate why rewriting/refactoring a feature just after writing the first version of it is so quick, relatively. And why it is often easier to write better code in a second pass. The first time you had to build the theory AND the code at the same time. In subsequent passes, you have the benefit of the theory from the start.
I think this concept is self-evident to most experienced engineers, but I have not heard quite as succinct an articulation of it before.
But you might argue the fact that most software is always adding features and changes is because it really is never a perfect representation of some target theory. In that case, the theory inside the heads of each person behind the software may even be incomplete compared to some perfect representation, and the work done by a company in the user/feature iteration cycle is the process of reconciling the drift between each of them towards some shared theory.
I don't think it's uncommon for parts of the theory already enshrined in implementation to be forgotten to time as it passes, if it's not regularly revisited and cogitated on.
That's an interesting point. My thought is that the theories of the software go well beyond programmers to everyone who interacts with the business process in question. Everyones theories are incomplete and aspirational though, sort of like a dream, while the code executing is the cold hard reality. Programmers have the closest theory to reality, sort of like a lucid dreamer, but even those with the deepest expertise are still subject to the deterministic outputs of code execution in production.
That reminds me of a comment on HN that I had to bookmark when I read it:
> Some processes try to break conceptual integrity. Micro services are one but Scrum as practiced usually tries to stick people into a blind valley where the horizon is months out rather than years. That leads to bad minmaxing behaviors, and/or covert channels being used to keep the wheels on.
Every world changing realization can look trivial from the other side. Understanding that people who don't have the amount of experience we have in our domain need to go through their own internal theory building process is both why it is so rare to find good teachers and what this epiphany is about.
> The value of computers is that you can write code once, and the computer can execute it repeatedly ad infinitum.
Until something changes and you need someone with a sound theory of the system to work out in a timely manner why it stopped working and how to get it working again. Bonus points for figuring out that this will happen again and that "running code" is not the product, the ability to keep the system running and evolving by changing code efficiently is.
have a look at Phillip Armour's "The Laws of Software Process: A New Model for the Production and Management of Software, 2003"
it talks about Software as knowledge medium, and effects thereof.. an attempt to put them things with their legs down, not up.
... software is not a product but a medium for storing knowledge, and software development is not a product-producing activity, it is a knowledge-acquiring activity.
... the real job is not writing the code, or even building the system - it is acquiring the necessary knowledge to build the system... Code is simply a by-product of this activity. The problem arises when we think the code, rather than the knowledge in the code, is the product.
... When we use models and mindsets that are rigid and deterministic to manage an activity that is fluid and variable, it is not surprising that people get disappointed.
and a consequence:
"... for the most part, (software) engineers do not _know_ how to build the systems they are trying to build; it's their job to _find_ out how to do it." i.e. programmers must be able to learn (and teach) - should learn that and/or be taught to it. All else are tools supporting that activity.
> ... the real job is not writing the code, or even building the system - it is acquiring the necessary knowledge to build the system... Code is simply a by-product of this activity. The problem arises when we think the code, rather than the knowledge in the code, is the product.
Absolutely true.
It is also true of all other disciplines of Engineering. The difference with Software Engineering seems to be that there are no Physical/Natural laws/constants to inform the Programmer of explicit boundaries/limitations and hence a stopping point.
> ...The value of computers is that you can write code once, and the computer can execute it repeatedly ad infinitum.
until, of course, someone updates a library that your code depends on or the OS changes the way it executes code or some other arbitrary change happens and your code is broken forever.
> The paper also talks about what happens when all the people who have a theory of a given program stop working on it. It dies. Yikes. It’s claimed that we can’t rebuild a theory from code and documentation.
In the text above word "theory" are used instead of "understanding". Not sure why.
Anyway, what exactly the hell Im doing in the last 10 years supporting legacy system mostly without documentation...
> when all the people who have a theory of a given program stop working on it. It dies.
This is only true of software of a particular level of complexity. For the most part, it simply isn't true. Humans made it (who also would routinely forget details about their own project) and humans can understanding it enough to build a working theory. If you can perform tests for something, you can deduce what it's doing, although the business case of why or specific experience with other approaches resulting in failures is often not recoverable by deduction.
The word "theory" is used because an essential aspect of this particular kind of understanding is that it lets you reason about the domain and the code's behavior. It's an apt term in that context.
While it's true that systems tend to be documented poorly, I think the article downplays the value of good documentation. Good docs describe everything that went into the system, from business requirements to implementation details, including things that were tried and abandoned (either because they didn't work or because business requirements changed), including code changes (e.g. "changed from DB table to in-memory array for speed; may need to change back if array grows too large").
This historical documentation, including historical codebase (think Git repo), is highly valuable. True, a new developer without the institutional knowledge is at a disadvantage, but that's the entire point of good code and good docs: so the next devs can pick up as efficiently as possible if/when they're called in.
I’m not the author, but my sense was that the word theory was being used because it was it couldn’t be explained fully. An “understanding” would instead but potentially full known and documented or made into an API, etc. This theory idea is to hint that there are even bigger ideas than can’t be written and you have to feel them and learn them from the original team to use them well yourself.
I’d love to hear from the original author how they think theory compares to a mental model. The biggest different is theories are known to be wrong, which fascinates me as an idea!
I have seen many pieces of code only make sense for a moment in time. The theory was right then, but wrong as the business evolved. Or sometimes visa-versa where the business was wrong, but the code worked beautifully for it.
You've been re-building the theory in your mind for the last 10 years. A better word for theory (I would propose) is mental model.
In fact, as soon as your mental model of the system is complete enough, you might as well re-implement it. It will be easier to understand and maintain.
The “software as theory” idea is helpful - thanks OP. Right now I’m dealing with some devilishly difficult GPU code, and I now understand that I’ve been working to reverse engineer the authors’ theory from their code. With much effort, I achieved a gratifying epiphany, and the code suddenly became clear! (Perhaps I developed a theory related to but not identical to that of the original authors.) Fortunately, I have an enlightened manager, and he was patient with the “theory building” process. Software degrades to garbage when a series of successive developers apply changes to it without a cogent theory. The process is self-reinforcing; the more degraded it becomes, the harder it is to develop a useful and accurate theory.
“ The process is self-reinforcing; the more degraded it becomes, the harder it is to develop a useful and accurate theory.” This is a really good point I think.
It feels like the Sprint / Agile practices that a lot of us use lead us to value expediency more than anything. So we'll try and find the quickest way to make a change that gets an existing program to do what we want. If we lack a working theory of the codebase that usually means we're doing something that runs counter to the overall design. And then over time everything gets worse and harder.
I want to say something about the pop-ups, which to have been much more discussed than what I wrote. (UX disaster as engagement bait?)
My desire in showing was to make the site feel more “alive” and to make the reader aware that other people had been there. I was trying to build a vibe of website as public space. Clearly this was not an approach that handles hacker news traffic and attitudes very well.
Secondly, I wanted to make readers aware of how much data is visible about them just from visiting a website.
I wanted it to feel like when you land on a drop shipping site that occasionaly tells you “Alice in Norwich just bought a widget. They're selling fast!”. You slowly realise that the data is real, and that the site actually can see where you live, who provides your internet. Etc. It was meant to be creepy.
Anyway, I've removed the feature now. It was clearly causing usability issues for some people, which was not what I intended. I'll think about other, better ways to get the effect that I had hoped for.
Finally, I'll say that it was at least interesting for me to see things like
“Someone else just connected to Johncom. They're in Kansas City, US, 64121 and are connecting with Spectrum”
“Someone else just connected to Johncom. They're in Cape Town, ZA, 8001 and are connecting with airmobile.co.za”
I got to learn about some new places, postcode formats, and ISPs.
I'm curious to read more of your thoughts on podcasting as a medium. I bet my goals & tastes in creating podcasts differ wildly from your goals & tastes in listening to them. And if I can be so bold: why give our show the time of day, but not something more tightly produced (which, perhaps, stands a better chance of offering high signal-to-noise)?
In any event, Jimmy and I appreciated your post. We're thrilled whenever someone digs in to a paper we've covered and finds it meaningful.
I usually find it very hard to remain deeply engaged with a podcast. I'll be focused for a few minutes, then my focus will shift and only later will I realise that I've been passively listening - absorbing it as a form of ambience but not properly engaging with what's being said. I think this is probably true for most listeners, especially because podcasts are often used as a soundtrack for doing some other task.
When we are not fully engaged with audio I think just go along with whatever's being said. We ignore logical leaps, and then pick up the thread later. But we do, I think, remain aware of the presenter's affect towards whatever topic is being discussed.
So a lot of the time I think when we listen to a podcast all we are really taking away is “what the topic was” and a sense of whether that's a thing we should feel positive or negative about. We don't critically engage with what's being said and whether the conclusions being reached are valid.
That's a lot of waffling, but the point that I'm really trying to get to is that podcasts seem to be more a medium for transmitting vibes than for transmitting complex thought.
This would be fine if podcasts were all entertainment, but when a lot of them are about world affairs, or psychology, or whatever, then I think it leads to people listening to podcasts believing they are educating themselves but actually just absorbing memes (in the mgs2 sense) from the presenters.
So mostly I think that podcasts are just a way for people to start believing things without understanding why they believe them. The more “Produced” a podcast is, the worse this effect probably is. And people listen to them ALL THE TIME. There's probably never been a better medium for spreading disinformation. lol
ANYWAY
I really liked your podcast, and it does some things that I think alleviate the issues I have.
* It's complex enough that if I become disengaged I can't pick up the thread, so I end up just pausing / rewinding.
* It's a conversation, and you as hosts don't agree a lot the time. You do some of the work of critical thinking for the listener.
* The editing is very funny.
I originally gave your podcast the time of day because I was considering going to a future of coding meetup in London, and wanted to know what the vibe would be. The meetup sold out while I was listening :)
For reference I think this probably partly explains my reluctance to use A.I. to help me code.
If I ask e.g. ChatGPT to just code something for me then the code it outputs is a black box, and there is no 'theory usage' in the parlance of the article. [Or I guess I'd have to recover the theory from the code it writes].
I've accepted by now that I'm putting myself at a disadvantage by not using A.I.
at work however. Maybe another way to think about it would be that A.I. allows us to use our higher level theoretical understanding when we interact with codebase.
What seems to work quite well is, you ask the AI to build something that fulfills your requirements. Then you ask questions about the implementation until you understand it in detail. Meanwhile you ask it to improve portions of the code based on your insights and your results after trying it out. So the black box morphs into a mental model that the machine has helped you to attain.
> The closest we can get to transferring a theory is to demonstrate the expression of the Theory to someone over and over again until they build their own theory. That theory won't be the same as ours.
This already has a term: "derived meaning". Derived meaning is what's actually created and stored in your head, and represents your particular brain's understanding of... something. It could be a thought, it could be a procedure, it could be a memory, it could be an emotion. But it can't be transferred to other brains; you can only hope that, by communication, you can reach some form of mutual understanding that at least fits the communication.
I have had a Theory of what software is myself, mostly based on "Programming as Theory Building," but it is good to see it put into words.
I struggle to build "theory of mind," which means I can't read code written by other people.
This means I can't get or keep a software job, so it sucks.
At the same time, it is a superpower in personal projects because I can somehow document my own theory of mind. It's counterintuitive, but my inability to build a theory of mind about other people causes me to assume less about what they know, which translates into good Theory docs.
I had a look at [1]. I believe it is interesting but for me, this document is hard to understand.
The thing is imo, you have a theory of mind on which you build. This building is done in a very structured way and works well for you. I believe the gist is, you have premises, eg. values of a code base, and build further on that, layer by layer.
The OP explains a pain point with sofware engineering, which also applies here: a theory cannot be fully expressed. The code and documentation flows out of the theory, they are artefacts, products of it. Still those are not encompassing the theory in itself, which in fact only exists in the originator's mind.
The job of many sw engineers is to get insights into such theories by inspecting the code and documentation, using it and approaching these from different angles. A bit like archeology.
I found Donella Meadows' book insightful, but I only read it after I understand system thinking so I might be biased. I wonder how insightful vs confusing it is to people from different paradigms
Readit News
I also think this is way off base:
> It means that the code base we create is not the true product of our work. The real product is the mental theory of that code base which
This is manifestly not the case. The value of computers is that you can write code once, and the computer can execute it repeatedly ad infinitum. As a programmer, your mental theory of the code base has value to its owners, but it's not the product. The code base is also not the product. The product is whatever output is created and consumed by the relevant stakeholders.
If you lost all of the code today, with the right understanding you could build it again relatively quickly. If you lost all that understanding, say all the developers quit, the program will no longer be adapted to customer needs potentially for years until that understanding is rebuilt.
I agree that "product" is probably not the right word, probably "asset" fits better. Losing that knowledge is like losing a manufacturing plant for your product. The plant isn't the product but it's a key asset for producing the product.
At a micro level, this helps articulate why rewriting/refactoring a feature just after writing the first version of it is so quick, relatively. And why it is often easier to write better code in a second pass. The first time you had to build the theory AND the code at the same time. In subsequent passes, you have the benefit of the theory from the start.
I think this concept is self-evident to most experienced engineers, but I have not heard quite as succinct an articulation of it before.
Yes, but it has nothing to do with the codebase. There are 10,000 ways of building the same product with entirely different codebases.
I don't think it's uncommon for parts of the theory already enshrined in implementation to be forgotten to time as it passes, if it's not regularly revisited and cogitated on.
That reminds me of a comment on HN that I had to bookmark when I read it:
> Some processes try to break conceptual integrity. Micro services are one but Scrum as practiced usually tries to stick people into a blind valley where the horizon is months out rather than years. That leads to bad minmaxing behaviors, and/or covert channels being used to keep the wheels on.
https://news.ycombinator.com/item?id=33923682
> The value of computers is that you can write code once, and the computer can execute it repeatedly ad infinitum.
Until something changes and you need someone with a sound theory of the system to work out in a timely manner why it stopped working and how to get it working again. Bonus points for figuring out that this will happen again and that "running code" is not the product, the ability to keep the system running and evolving by changing code efficiently is.
have a look at Phillip Armour's "The Laws of Software Process: A New Model for the Production and Management of Software, 2003" it talks about Software as knowledge medium, and effects thereof.. an attempt to put them things with their legs down, not up.
... software is not a product but a medium for storing knowledge, and software development is not a product-producing activity, it is a knowledge-acquiring activity.
... the real job is not writing the code, or even building the system - it is acquiring the necessary knowledge to build the system... Code is simply a by-product of this activity. The problem arises when we think the code, rather than the knowledge in the code, is the product.
... When we use models and mindsets that are rigid and deterministic to manage an activity that is fluid and variable, it is not surprising that people get disappointed.
and a consequence:
"... for the most part, (software) engineers do not _know_ how to build the systems they are trying to build; it's their job to _find_ out how to do it." i.e. programmers must be able to learn (and teach) - should learn that and/or be taught to it. All else are tools supporting that activity.
Absolutely true.
It is also true of all other disciplines of Engineering. The difference with Software Engineering seems to be that there are no Physical/Natural laws/constants to inform the Programmer of explicit boundaries/limitations and hence a stopping point.
until, of course, someone updates a library that your code depends on or the OS changes the way it executes code or some other arbitrary change happens and your code is broken forever.
Ok, let's use that word above since the article uses it as well.
In the text above word "theory" are used instead of "understanding". Not sure why. Anyway, what exactly the hell Im doing in the last 10 years supporting legacy system mostly without documentation...
This is only true of software of a particular level of complexity. For the most part, it simply isn't true. Humans made it (who also would routinely forget details about their own project) and humans can understanding it enough to build a working theory. If you can perform tests for something, you can deduce what it's doing, although the business case of why or specific experience with other approaches resulting in failures is often not recoverable by deduction.
Why, why they used word "theory" in the first place?
This historical documentation, including historical codebase (think Git repo), is highly valuable. True, a new developer without the institutional knowledge is at a disadvantage, but that's the entire point of good code and good docs: so the next devs can pick up as efficiently as possible if/when they're called in.
I’d love to hear from the original author how they think theory compares to a mental model. The biggest different is theories are known to be wrong, which fascinates me as an idea!
I have seen many pieces of code only make sense for a moment in time. The theory was right then, but wrong as the business evolved. Or sometimes visa-versa where the business was wrong, but the code worked beautifully for it.
Deleted Comment
It feels like the Sprint / Agile practices that a lot of us use lead us to value expediency more than anything. So we'll try and find the quickest way to make a change that gets an existing program to do what we want. If we lack a working theory of the codebase that usually means we're doing something that runs counter to the overall design. And then over time everything gets worse and harder.
I want to say something about the pop-ups, which to have been much more discussed than what I wrote. (UX disaster as engagement bait?)
My desire in showing was to make the site feel more “alive” and to make the reader aware that other people had been there. I was trying to build a vibe of website as public space. Clearly this was not an approach that handles hacker news traffic and attitudes very well.
Secondly, I wanted to make readers aware of how much data is visible about them just from visiting a website.
I wanted it to feel like when you land on a drop shipping site that occasionaly tells you “Alice in Norwich just bought a widget. They're selling fast!”. You slowly realise that the data is real, and that the site actually can see where you live, who provides your internet. Etc. It was meant to be creepy.
Anyway, I've removed the feature now. It was clearly causing usability issues for some people, which was not what I intended. I'll think about other, better ways to get the effect that I had hoped for.
Finally, I'll say that it was at least interesting for me to see things like
“Someone else just connected to Johncom. They're in Kansas City, US, 64121 and are connecting with Spectrum”
“Someone else just connected to Johncom. They're in Cape Town, ZA, 8001 and are connecting with airmobile.co.za”
I got to learn about some new places, postcode formats, and ISPs.
I'm curious to read more of your thoughts on podcasting as a medium. I bet my goals & tastes in creating podcasts differ wildly from your goals & tastes in listening to them. And if I can be so bold: why give our show the time of day, but not something more tightly produced (which, perhaps, stands a better chance of offering high signal-to-noise)?
In any event, Jimmy and I appreciated your post. We're thrilled whenever someone digs in to a paper we've covered and finds it meaningful.
I usually find it very hard to remain deeply engaged with a podcast. I'll be focused for a few minutes, then my focus will shift and only later will I realise that I've been passively listening - absorbing it as a form of ambience but not properly engaging with what's being said. I think this is probably true for most listeners, especially because podcasts are often used as a soundtrack for doing some other task.
When we are not fully engaged with audio I think just go along with whatever's being said. We ignore logical leaps, and then pick up the thread later. But we do, I think, remain aware of the presenter's affect towards whatever topic is being discussed.
So a lot of the time I think when we listen to a podcast all we are really taking away is “what the topic was” and a sense of whether that's a thing we should feel positive or negative about. We don't critically engage with what's being said and whether the conclusions being reached are valid.
That's a lot of waffling, but the point that I'm really trying to get to is that podcasts seem to be more a medium for transmitting vibes than for transmitting complex thought.
This would be fine if podcasts were all entertainment, but when a lot of them are about world affairs, or psychology, or whatever, then I think it leads to people listening to podcasts believing they are educating themselves but actually just absorbing memes (in the mgs2 sense) from the presenters.
So mostly I think that podcasts are just a way for people to start believing things without understanding why they believe them. The more “Produced” a podcast is, the worse this effect probably is. And people listen to them ALL THE TIME. There's probably never been a better medium for spreading disinformation. lol
ANYWAY
I really liked your podcast, and it does some things that I think alleviate the issues I have.
* It's complex enough that if I become disengaged I can't pick up the thread, so I end up just pausing / rewinding. * It's a conversation, and you as hosts don't agree a lot the time. You do some of the work of critical thinking for the listener. * The editing is very funny.
I originally gave your podcast the time of day because I was considering going to a future of coding meetup in London, and wanted to know what the vibe would be. The meetup sold out while I was listening :)
If I ask e.g. ChatGPT to just code something for me then the code it outputs is a black box, and there is no 'theory usage' in the parlance of the article. [Or I guess I'd have to recover the theory from the code it writes].
I've accepted by now that I'm putting myself at a disadvantage by not using A.I. at work however. Maybe another way to think about it would be that A.I. allows us to use our higher level theoretical understanding when we interact with codebase.
This already has a term: "derived meaning". Derived meaning is what's actually created and stored in your head, and represents your particular brain's understanding of... something. It could be a thought, it could be a procedure, it could be a memory, it could be an emotion. But it can't be transferred to other brains; you can only hope that, by communication, you can reach some form of mutual understanding that at least fits the communication.
I have had a Theory of what software is myself, mostly based on "Programming as Theory Building," but it is good to see it put into words.
I struggle to build "theory of mind," which means I can't read code written by other people.
This means I can't get or keep a software job, so it sucks.
At the same time, it is a superpower in personal projects because I can somehow document my own theory of mind. It's counterintuitive, but my inability to build a theory of mind about other people causes me to assume less about what they know, which translates into good Theory docs.
My best example is [1].
[1]: https://git.gavinhoward.com/gavin/bc/src/commit/22253a3a64db...
The thing is imo, you have a theory of mind on which you build. This building is done in a very structured way and works well for you. I believe the gist is, you have premises, eg. values of a code base, and build further on that, layer by layer.
The OP explains a pain point with sofware engineering, which also applies here: a theory cannot be fully expressed. The code and documentation flows out of the theory, they are artefacts, products of it. Still those are not encompassing the theory in itself, which in fact only exists in the originator's mind.
The job of many sw engineers is to get insights into such theories by inspecting the code and documentation, using it and approaching these from different angles. A bit like archeology.
When I launch my business, that will be an essential part of my product.
So can you give me specific feedback on that document?
https://en.wikipedia.org/wiki/Systems_thinking?useskin=vecto...