> I disagree strongly. I think the articulation of what you’re building, and why, is far more important. Basically, the idea. Your intent.
Nobody gets paid for "intent". You get paid for the result. I do not buy a video game that "intended to be good" and "had a great specification". It feels so weird that I tough that it was parody.
Next ... the bridge collapsed but that is beyond the point. Look at the specifications!
Nobody is saying you shouldn't have a good understanding of the bridge that was built.
The argument is that you need to understand why it failed, in the lifecycle between what we intended to build vs. what we built.
There's a massive difference between a bad design and bad materials, both of which could have caused it to fall.
You can get a bad design idea from the code/bridge as well, but it's pretty glaring when the intent said, "we believe balsa wood is the best bridge material", or "we decided to save 49% of our costs by getting our nuts and bolts from the Lego shop."
the author, I imagine, would object that the bridge should have specified that it is not supposed to collapse.
And if it did, that the specific load that made it collapse should have been specifically mentioned in the spec.
And if it was, well just wait until agents become the magical machine gods he assumes they are, then bridge collapses will be a thing of the past.
but let's be real, he and everyone else are machine generating their specs anyway, and the relevant spec didnt mention anything about bridges collapsing but instead 250 pages of llm waffling about the tensile strength of different structural materials, load patterns from different tyre treads, the effect of climate change on el nino and weather patterns for wind, and the bridge still fell down, because nobody had any idea what they were doing
Code being highest priority is the last line of defense against human intent being misunderstood. If it isn't given the highest priority, the last line of defense for human intent is done during the spec creation. Am I getting that wrong?
I'd rather have a car built by people who made sure the code was highest priority and the code driving the assembly line robots was up to spec, versus having a car built by people who made sure the spec was highest priority, and the code driving the assembly line was not.
> I think the most important thing in any project you’re building...is how completely and accurately you articulate exactly what you want.
That's what code does.
I think he really wants to be having a debate about whether we ought to be using different coding languages, more based on natural languages, more declarative.
I think the law provides an interesting perspective. It has a technical, formalized language, built out of a natural language. Since laws and contracts can be very high-stakes, the technical/formalized aspects arose out of a need to express hard constraints using a language whose complexities seem to be built more for story-telling.
Laws are full of holes and contradictions. For example, megacorps evade tax. We want them to pay the tax. See, the _intent_ is for them to pay, but the _execution_ of the intent fails. If you take the current laws as the basis and want to improve upon them, how do you improve? What counts as improvement? "Megacorps must pay tax too" is a clear intent/goal. It captures the requirement. If you read the laws, can you deduce this requirement? Can you improve upon them without the requirement?
Odd I thought that only proves them right, it's a best attempt with natural language by capital and the state, the two major forces of power in our society, and they still get burned.
For the record, psychology research has demonstrated that humans do not think in language. This was a popular myth started by someone in the 1930's or so, I think, leading to authoritarian ideas about thought control via language control. People still won't give up on it...
I have found that databases are the exception where documentation is critical, in that knowledge of what we do to the data (described in program logic) is completely different from knowledge of what the data means. Reverse-engineering that meaning often takes me longer than anything else.
Beyond that, however, English is a horribly ambiguous, contradictory and complicated programming language. It's a literal anarchy. Had it not been for primitive 1950's hardware, I suspect people would have refused to invent programming languages and insisted on AI-processed English anyhow. For now I guess we'll work as computational attorneys...
My thoughts are without a doubt closer to code than writing.
Thoughts are more often than not non-linear, so putting them into writing is challenging.
Meanwhile, when I think of code—and also when I physically write code—it's always possible to leave holes and stubs to be filled in later.
Good point. Writing has to create a narrative in a way code does not. It's generally very structured when written for others and not just ourselves, and I would say you can probably be looser with writing than code in the small but once you get into paragraphs, code starts being more flexible (I don't mean theoretically just my own opinion on what's common). Ie codes syntax is fixed but the composition is very flexible while writing prose is very flexible but you will find only so many ways of writing paragraphs or pages because we are so often using writing to create a narrative arc.
There's no one true answer when it comes to the perspectivity of the mind, of which language is a part of. For some people, writing is closest to thought. For others, code is closer. Others still might find mathematics a better means of expression. YMMV with any one idea here.
>Say you want to draw a perfect picture of an owl. You have this beautiful image of it in your mind. But you can’t draw very well, and in this analogy the drawing is the code. So what comes out is a stick-figure owl that’s barely recognizable as an owl.
>In the code-is-the-source-of-truth version, that stick figure is now the authoritative artifact. We analyze it, document it, take notes on its proportions, and spend a whole bunch of time iterating on it. We’re running in circles around a bad drawing.
My only disagreement with the post is over whether articulating is is the main bottleneck. Right now, there are still issues and oversights humans would tend not to make even if you have model context and documentation accurately and clearly capturing your full intent.
Each year will decrease the rate of this, but software engineering will probably need until maybe 2030 until we've crossed a threshold towards solely being product managers/designers. This advice still applies today, but you do need more wrangling on top.
The belief that the owl in the mind is perfect is a delusion. Intentions, writing, ideas are all highly non-specific. They might not even work at all when they make contact with reality. This is why lots of people can’t draw a functioning bicycle from memory. Delusion.
Certainly natural language prose can articulate human-level concepts and priorities that code cannot. The fact that LLMs can interpret and apply these things is novel and useful. I agree with the author there is a lot of juice that can be squeezed out of this.
But on the other hand, whenever I start writing code (with or without LLM assistance), there is always a huge amount of learning and iteration that happens. No matter how thoroughly I thought through everything, or how perfect the idea seemed in my head, it always evolved once the implementation was concrete. And furthermore, once you have code running and people depend on it, the code is the reality, and any other documentation or vision statements have a tendency to go stale. Obviously AI makes it easier to keep documentation up-to-date, but the disconnect between the idea of the system and what the system actually does remains.
For this reason I don't see any huge value in deliberately moving to a higher layer. All the same modalities can still be applied with AI: comments, commit messages, PR messages, literate programming, READMEs, AGENT.mds, tech specs, tech 1-pagers, vision statements, etc. I write a doc when it's useful to communicate to one or more parties, otherwise I try to keep everything as minimal and possible, often that means just live in the code.
Why not use gherkin given/when/then stories, and build E2E runners and maybe also unit tests for them? I don’t understand why a new spec format is necessary, which forever binds you to using agents for evaluation. Deterministic tests also have the advantage that they are harder to cheat on. If they are green, they give me a strong signal I can trust.
The brain being full of thoughts, will, sensors, and tension of conflicting values must translate from gray space to meat space to someone else's gray space.
Of course what is articulation but expression of the above into a medium that results in the reality being made manifest.
It was at the Tower of Babel where intent was disrupted by requiring chained levels of translation. From Brain to Speech or Writing to another's language through the filters of culture and nations, the ability to communicate was disrupted.
Code just happens to be one additional layer of translation.
A full spec is indistinguishable from code though.
That's the bottom of the problem. You can think all you want in your spec doc, you won't fully solve all the problems that you will face during implementation.
That's why ports are easy with LLMs, cause the code implicitly carries all the spec.
Sure, there may be a gap between the code and the idea behind the spec, but it can be argued that the gap between the spec as a document and the idea behind the spec is just as wide, and in fact doesn't take into account the constraint of reality.
LLMs generally suck at taking the initiative. Tell it to build a report, it's going to do it, but then you'll have to iterate a lot to make sure it's producing it the exact way you want it.
Peirce I think successfully mapped out the concept of the firstness/secondness/thirdness.
The only way you are getting close to expressing firstness is through high speed, unedited word association poetry.
Humans don't really have introspection, we don't have access to what's going on in every subsystem, we don't even have control, otherwise we could think ourselves to death ala breaking emacs with the right line of lisp.
The idea that the thought or intent in your brain survives semantic translation is... well, it can only kinda happen. It can be a target but thinking it's possible in an absolute sense is the old map/terrain mistake.
I think fast iteration with image mocks and wire frame mocks is sufficient, understanding the process of rapid testing with isolated toys before locking in design is the best we can get.
you can't write emotions on paper either. You can write things that evoke emotion in the reader, but code can do that too. It happens quite often to me, at work. Often negative but occasionally positive
Then why do I greatly prefer reading code snippets over language in basically every setting that software is involved in? I say this as a hyper verbal person (ie: much of my internal world is dominated by language and I could never shut the fuck up as a kid, or today, really)
I don't think any one form is close to my thought and I can definitely say diagrams and code often sit closer to how I think about systems than language.
I also think articulation is also a separate skill. I've met brilliant people that weren't great writers but that doesn't stop them from designing and understanding or building complex things with great accuracy
What argument? Matt is behind the times but accepts AI?
"Matt is a brilliant old-school developer: a true software engineer. And he’s been using AI to enhance his capabilities to an extraordinary degree. His development skills are spectacular, and have been starred more than almost any other skills repo on GitHub."
Nauseating. The article was written probably after the Djikstra article about the foolishness of natural language in programming was posted, just for damage control and for people having a talking point link to "refute" Djikstra on Twitter.
I’ve gained great utility from a colloquialism in certain circles of mine and feel it may be of some value: “writing is a euphemism for thinking”
Used in casual rebuttal when anyone in the group declares they want to write or become a writer, whether it be prose, music, code or even extrapolated to art.
> I disagree strongly. I think the articulation of what you’re building, and why, is far more important. Basically, the idea. Your intent.
Nobody gets paid for "intent". You get paid for the result. I do not buy a video game that "intended to be good" and "had a great specification". It feels so weird that I tough that it was parody.
Next ... the bridge collapsed but that is beyond the point. Look at the specifications!
Nobody is saying you shouldn't have a good understanding of the bridge that was built.
The argument is that you need to understand why it failed, in the lifecycle between what we intended to build vs. what we built.
There's a massive difference between a bad design and bad materials, both of which could have caused it to fall.
You can get a bad design idea from the code/bridge as well, but it's pretty glaring when the intent said, "we believe balsa wood is the best bridge material", or "we decided to save 49% of our costs by getting our nuts and bolts from the Lego shop."
the author, I imagine, would object that the bridge should have specified that it is not supposed to collapse.
And if it did, that the specific load that made it collapse should have been specifically mentioned in the spec.
And if it was, well just wait until agents become the magical machine gods he assumes they are, then bridge collapses will be a thing of the past.
but let's be real, he and everyone else are machine generating their specs anyway, and the relevant spec didnt mention anything about bridges collapsing but instead 250 pages of llm waffling about the tensile strength of different structural materials, load patterns from different tyre treads, the effect of climate change on el nino and weather patterns for wind, and the bridge still fell down, because nobody had any idea what they were doing
Code being highest priority is the last line of defense against human intent being misunderstood. If it isn't given the highest priority, the last line of defense for human intent is done during the spec creation. Am I getting that wrong?
I'd rather have a car built by people who made sure the code was highest priority and the code driving the assembly line robots was up to spec, versus having a car built by people who made sure the spec was highest priority, and the code driving the assembly line was not.
> I think the most important thing in any project you’re building...is how completely and accurately you articulate exactly what you want.
That's what code does.
I think he really wants to be having a debate about whether we ought to be using different coding languages, more based on natural languages, more declarative.
I think the law provides an interesting perspective. It has a technical, formalized language, built out of a natural language. Since laws and contracts can be very high-stakes, the technical/formalized aspects arose out of a need to express hard constraints using a language whose complexities seem to be built more for story-telling.
Laws are full of holes and contradictions. For example, megacorps evade tax. We want them to pay the tax. See, the _intent_ is for them to pay, but the _execution_ of the intent fails. If you take the current laws as the basis and want to improve upon them, how do you improve? What counts as improvement? "Megacorps must pay tax too" is a clear intent/goal. It captures the requirement. If you read the laws, can you deduce this requirement? Can you improve upon them without the requirement?
Odd I thought that only proves them right, it's a best attempt with natural language by capital and the state, the two major forces of power in our society, and they still get burned.
For the record, psychology research has demonstrated that humans do not think in language. This was a popular myth started by someone in the 1930's or so, I think, leading to authoritarian ideas about thought control via language control. People still won't give up on it...
I have found that databases are the exception where documentation is critical, in that knowledge of what we do to the data (described in program logic) is completely different from knowledge of what the data means. Reverse-engineering that meaning often takes me longer than anything else.
Beyond that, however, English is a horribly ambiguous, contradictory and complicated programming language. It's a literal anarchy. Had it not been for primitive 1950's hardware, I suspect people would have refused to invent programming languages and insisted on AI-processed English anyhow. For now I guess we'll work as computational attorneys...
My thoughts are without a doubt closer to code than writing. Thoughts are more often than not non-linear, so putting them into writing is challenging. Meanwhile, when I think of code—and also when I physically write code—it's always possible to leave holes and stubs to be filled in later.
Good point. Writing has to create a narrative in a way code does not. It's generally very structured when written for others and not just ourselves, and I would say you can probably be looser with writing than code in the small but once you get into paragraphs, code starts being more flexible (I don't mean theoretically just my own opinion on what's common). Ie codes syntax is fixed but the composition is very flexible while writing prose is very flexible but you will find only so many ways of writing paragraphs or pages because we are so often using writing to create a narrative arc.
There's no one true answer when it comes to the perspectivity of the mind, of which language is a part of. For some people, writing is closest to thought. For others, code is closer. Others still might find mathematics a better means of expression. YMMV with any one idea here.
Mel the real programmer would disagree.
[1] - https://users.cs.utah.edu/~elb/folklore/mel.html
"If a program can't rewrite its own code", he asked, "what good is it?"
(BTW, the poem like formatting was a happy accident.)
Good post. I like this example:
>Say you want to draw a perfect picture of an owl. You have this beautiful image of it in your mind. But you can’t draw very well, and in this analogy the drawing is the code. So what comes out is a stick-figure owl that’s barely recognizable as an owl.
>In the code-is-the-source-of-truth version, that stick figure is now the authoritative artifact. We analyze it, document it, take notes on its proportions, and spend a whole bunch of time iterating on it. We’re running in circles around a bad drawing.
My only disagreement with the post is over whether articulating is is the main bottleneck. Right now, there are still issues and oversights humans would tend not to make even if you have model context and documentation accurately and clearly capturing your full intent.
Each year will decrease the rate of this, but software engineering will probably need until maybe 2030 until we've crossed a threshold towards solely being product managers/designers. This advice still applies today, but you do need more wrangling on top.
A great point. Yeah, it's not all an articulation issue.
The belief that the owl in the mind is perfect is a delusion. Intentions, writing, ideas are all highly non-specific. They might not even work at all when they make contact with reality. This is why lots of people can’t draw a functioning bicycle from memory. Delusion.
There's a time and a place for both?
Certainly natural language prose can articulate human-level concepts and priorities that code cannot. The fact that LLMs can interpret and apply these things is novel and useful. I agree with the author there is a lot of juice that can be squeezed out of this.
But on the other hand, whenever I start writing code (with or without LLM assistance), there is always a huge amount of learning and iteration that happens. No matter how thoroughly I thought through everything, or how perfect the idea seemed in my head, it always evolved once the implementation was concrete. And furthermore, once you have code running and people depend on it, the code is the reality, and any other documentation or vision statements have a tendency to go stale. Obviously AI makes it easier to keep documentation up-to-date, but the disconnect between the idea of the system and what the system actually does remains.
For this reason I don't see any huge value in deliberately moving to a higher layer. All the same modalities can still be applied with AI: comments, commit messages, PR messages, literate programming, READMEs, AGENT.mds, tech specs, tech 1-pagers, vision statements, etc. I write a doc when it's useful to communicate to one or more parties, otherwise I try to keep everything as minimal and possible, often that means just live in the code.
Why not use gherkin given/when/then stories, and build E2E runners and maybe also unit tests for them? I don’t understand why a new spec format is necessary, which forever binds you to using agents for evaluation. Deterministic tests also have the advantage that they are harder to cheat on. If they are green, they give me a strong signal I can trust.
Great article.
The brain being full of thoughts, will, sensors, and tension of conflicting values must translate from gray space to meat space to someone else's gray space.
Of course what is articulation but expression of the above into a medium that results in the reality being made manifest.
It was at the Tower of Babel where intent was disrupted by requiring chained levels of translation. From Brain to Speech or Writing to another's language through the filters of culture and nations, the ability to communicate was disrupted.
Code just happens to be one additional layer of translation.
A full spec is indistinguishable from code though.
That's the bottom of the problem. You can think all you want in your spec doc, you won't fully solve all the problems that you will face during implementation.
That's why ports are easy with LLMs, cause the code implicitly carries all the spec.
Sure, there may be a gap between the code and the idea behind the spec, but it can be argued that the gap between the spec as a document and the idea behind the spec is just as wide, and in fact doesn't take into account the constraint of reality.
LLMs generally suck at taking the initiative. Tell it to build a report, it's going to do it, but then you'll have to iterate a lot to make sure it's producing it the exact way you want it.
Peirce I think successfully mapped out the concept of the firstness/secondness/thirdness.
The only way you are getting close to expressing firstness is through high speed, unedited word association poetry.
Humans don't really have introspection, we don't have access to what's going on in every subsystem, we don't even have control, otherwise we could think ourselves to death ala breaking emacs with the right line of lisp.
The idea that the thought or intent in your brain survives semantic translation is... well, it can only kinda happen. It can be a target but thinking it's possible in an absolute sense is the old map/terrain mistake.
I think fast iteration with image mocks and wire frame mocks is sufficient, understanding the process of rapid testing with isolated toys before locking in design is the best we can get.
Someone has yet to write emotions in code.
You haven’t been reading my comments, pal.
you can't write emotions on paper either. You can write things that evoke emotion in the reader, but code can do that too. It happens quite often to me, at work. Often negative but occasionally positive
How about emoticons? ;)
Then why do I greatly prefer reading code snippets over language in basically every setting that software is involved in? I say this as a hyper verbal person (ie: much of my internal world is dominated by language and I could never shut the fuck up as a kid, or today, really)
I don't think any one form is close to my thought and I can definitely say diagrams and code often sit closer to how I think about systems than language.
I also think articulation is also a separate skill. I've met brilliant people that weren't great writers but that doesn't stop them from designing and understanding or building complex things with great accuracy
Another redefinition booster article:
War is peace, freedom is slavery, I know better than Djikstra.
Great point. Alternatively, you could have addressed the arguments.
What argument? Matt is behind the times but accepts AI?
"Matt is a brilliant old-school developer: a true software engineer. And he’s been using AI to enhance his capabilities to an extraordinary degree. His development skills are spectacular, and have been starred more than almost any other skills repo on GitHub."
Nauseating. The article was written probably after the Djikstra article about the foolishness of natural language in programming was posted, just for damage control and for people having a talking point link to "refute" Djikstra on Twitter.
Really? I'd have thought that would be obvious to 99% of the population...
Here is another take: Speaking is closer to thought that writing! Can I write a blog post now?
gestures with hand for you to proceed
I’ve gained great utility from a colloquialism in certain circles of mine and feel it may be of some value: “writing is a euphemism for thinking”
Used in casual rebuttal when anyone in the group declares they want to write or become a writer, whether it be prose, music, code or even extrapolated to art.