Design for Understandability
25 points by jschuster
25 points by jschuster
I've found myself on a mission to promote designing for understandability for at least 4 years now, predating the rise of LLMs. I think LLMs highlight an existing problem that we weren't taking seriously back when we were confusing humans instead of machines.
For example, I think if we'd made better progress on this as an industry, MCP likely wouldn't have come into existence. I suspect that instead as an industry we would have likely made small modifications to existing solutions.
So it's all mighty interesting to me!
if we'd made better progress on this as an industry, MCP likely wouldn't have come into existence
Can you say more about that?
My feeling is that if all our UIs and APIs were easy to use them we'd just let the LLM screen-scrape them or make API requests according to the structure in the Swagger files or whatever. Why would we need to make a separate thing for the LLM if the thing we made for ourselves was easy?
Shouting into the void doesn't solve anything. But it's brain rot hot takes like these that makes me not want to have anything to do with the tech industry.
LLMs are like a sloppy intern says the author. It's your responsibility to make sure the code they generate is good enough to release.
But that's now how friends Altman and Amodei sell LLMs, is it? I seem to remember they said programmers are now obsolete or something to that effect. Which one is it then?
Repeat after me: shifting responsibility onto humans for probabilistic fantasies is disingenuous and morally bankrupt.
Also shout out for calling writing your own code "the old fashioned way".
Edit: "brain rot" was mean. I shouldn't have let my frustration with the author's hot take get the better of me.
As kenballus said, I think we're kind of in agreement? I have a lot of problems with LLMs both in how they're trained and in how people are being pushed to use them, often in what I would deem irresponsible ways. But this talk was originally for an internal Google audience, which is much more AI-positive overall, so I was going for kind of a harm-reduction approach. Basically, "Using an LLM does not absolve you of responsibility for your code, so if you choose to use LLMs to code, here are some things you can do to do so (relatively) responsibly."
I completely disagree with the whole "programmers are obsolete now" takes. If one can get over the ethical concerns (and that's a big if), I do think there's value in using LLMs for software engineering, but it looks very different from what some CEOs are pushing. Maybe more like a 5-10% improvement than the 5-10X improvements some people claim, but I hesitate to even put numbers on it. (And that's not even getting into the economics of it all)
I'm not sure how this came across as "shifting responsibility onto humans for probabilistic fantasies". I'd be glad to hear where my message got lost if you care to share.
Your writing was clear and sober from my perspective.
A lot of people seem to assume that people who accept today's reality are all the way down the rabbit hole, which couldn't be farther from the truth.
There are some obvious reasons why agentic coding is taking off, but also MANY downsides, some of which may never go away.
The hardest parts of software development have always revolved around gaps in human ability to communicate. For instance, stakeholders no better at communicating what we want to an agent than they were with an engineering team.
Right now, agents are far worse at that communication than people. And, for all their knowledge, they tend to be easily distracted from the big picture, and not consider "common sense".
Too many people confuse knowledge with wisdom, especially since our brains like to anthropomorphize. I see a lot of people outsourcing themselves to an agent, not just in their coding, but doing things like cut-and-pasting authoritative-sounding assessments that are absolutely wrong, because they assume the agent is right, and don't even think to dig in.
I personally see it as a tool for scaling myself that trades off speed for quality. Getting even to an acceptable quality bar requires micromanagement. From what I have seen, hands off agent loops may eventually will tick all the boxes on a requirements matrix, but for any large project will end up too brittle to actually scale well, because of how bad both sides are at the up-front communication :)
People who micromanage the work can get to good enough results if they've got the right expertise to make sure of it. But I totally agree with you that it's not quite the improvement it feels like, if you demand any reasonable quality.
It's situational for sure, and I do think 10x for prototype quality (meaning, it SHOULD be thrown away) is realistic.
Hi. Thanks for taking the time to reply despite my aggressively phrased post. In hindsight it was needlessly aggressive, and for that I do apologize.
My frustration comes from the fact that, even if well intended and coming from a moderate place, this attitude plays into the LLM pushers agenda. It's presented as inevitable. It's not. It's not "get with the times or become obsolete". It's an immoral money grab by a bunch of rich assholes. We don't have to be complicit in it. Accepting that humans are responsible for LLM output while at the same time having tens of thousands of jobs cut "because LLMs" is just rolling over and accepting that this is how things should be.
LLM vendors should be responsible for every outage caused by LLM produced code. Decision makers who mandate LLM use (or who make its use unavoidable) should be responsible as well.
Once again, I apologize for the aggressive tone and the ad hominem in my original post. That was uncalled for. But I stand by the rest of what I said.
I don't understand what you're trying to say. Your comment comes off kind of confrontational, even though it sounds like you agree with the author for the most part.
LLMs are like a sloppy intern says the author. ... But that's now [sic] how friends Altman and Amodei sell LLMs, is it? ... Which one is it then?
If the article were written by an LLM booster, then your statements here would make sense, but the author's last two posts are about the shortcomings of LLMs. I don't think there's a contradiction here; the author clearly just disagrees with the CEO types.
"shifting responsibility onto humans for probabilistic fantasies"
That's always been done, long before AI. It describes any engineer who got promoted into management.
It's often tough to make that transition, because the people working for you are imperfect, and probably not going to do things exactly how you'd want them done yourselves, etc. But:
I wouldn't have opened Pandora's box, but it is open. And with it, every developer just got promoted to manager, in a way.
The biggest concern is how to ensure, in the long term, people have a good path to build the technical skills in enough bulk to apply the good judgement and oversight that a manager needs to have.
These are all great ideas that should already be mainstream. I don’t think they solve the problem of too much code. It takes a lot of time to read and understand the best code even when designed for understandability.
With enough tests and not very much architectural direction you can get agents to generate a ton of correct code that doesn’t rely on any antipatterns. It’s still a ton of code and if you have to actually read and understand it, it’s brutal. I’m certainly not saying that you shouldn’t use AI to generate readable code, but I certainly haven’t worked out how to make it work out nicely when undertaking a substantial project if understanding the code is important.
I agree they "should" already be mainstream. In practice, I see a lot of cases where they should be applied but aren't.
Nice post. Personally, I've always believed that the essence of writing maintainable code is minimizing the amount of additional information you need to reason about any particular function or module. A lot of the practices in the post fall out as corollaries of this general idea.
I enjoyed this. Thanks for writing it! One point that I'd like to see addressed is how performance requirements can interfere with this approach.
e.g., yesterday, I paired with someone at RC who was writing a Scheme stdlib.
We started with this list-copy:
(define (list-copy l)
(if (null? l)
'()
(cons (car l) (list-copy (cdr l)))))
This function is easy to understand in 2 ways:
...but it's not tail recursive.
So we rewrote it like this, using a previously-defined tail recursive shallow-copying reverse:
(define (list-copy l)
(reverse (reverse l)))
It's still relatively easy to convince yourself that this function does copy the list, but it's less obvious why we chose to use this algorithm over any other (because being tail recursive isn't explicitly mentioned anywhere).
...but this iterates over the list twice. Can we do even better? Yeah, but it's gonna be gross:
(define (list-copy items)
(let ((lose (lambda () (error:not-a list? items 'LIST-COPY))))
(cond ((pair? items)
(let ((head (cons (car items) '())))
(let loop ((list (cdr items)) (previous head))
(cond ((pair? list)
(let ((new (cons (car list) '())))
(set-cdr! previous new)
(loop (cdr list) new)))
((not (null? list)) (lose))))
head))
((null? items) items)
(else (lose)))))
(from MIT Scheme)
This list-copy is hard to understand, but it also performs the best. This is an instance of a general pattern: the more optimized something gets, the more difficult it becomes to understand. Another example could be made by comparing the naive byte-by-byte strcpy to the 64-bit wide register-SIMD version, to the full-blown vectorized version.
The usual solution to this is good interfaces ("design by contract"), but maybe all that really does is put layers of paint on top of the nasty, optimized code at the bottom?