[HN Gopher] We should revisit literate programming in the agent era
___________________________________________________________________
We should revisit literate programming in the agent era
Author : horseradish
Score : 68 points
Date : 2026-03-08 19:58 UTC (3 hours ago)
(HTM) web link (silly.business)
(TXT) w3m dump (silly.business)
| sublinear wrote:
| > This is especially important if the primary role of engineers
| is shifting from writing to reading.
|
| This was always the primary role. The only people who ever said
| it was about writing just wanted an easy sales pitch aimed at
| everyone else.
|
| Literate programming failed to take off because with that much
| prose it inevitably misrepresents the actual code. Most normal
| comments are bad enough.
|
| It's hard to maintain any writing that doesn't actually change
| the result. You can't "test" comments. The author _doesn 't even
| need to know why the code works_ to write comments that are
| convincing at first glance. If we want to read lies influenced by
| office politics, we already have the rest of the docs.
| c0rp4s wrote:
| You're right that you can't test comments, but you can test the
| code they describe. That's what reproducibility bundles do in
| scientific computing ;; the prose says "we filtered variants
| with MAF < 0.01", and the bundle includes the exact shell
| command, environment, and checksums so anyone can verify the
| prose matches reality. The prose becomes a testable claim
| rather than a decorative comment. That said, I agree the
| failure mode of literate programming is prose that drifts from
| code. The question is whether agents reduce that drift enough
| to change the calculus.
| ares623 wrote:
| I don't buy that. Writing is taking a bad rap from all this.
| Writing _is_ a form of more intense reading. Reading on
| steroids, as they say. If reading is considered good, writing
| should be considered better.
| bigyabai wrote:
| Writing in that draft style is really only useful because a)
| you read the results and b) you write an improved version at
| the end. Drafting forever is not considered "better" because
| someone (usually you) has to sift through the crap to find
| the good parts.
|
| This is especially pronounced in the programming workplace,
| where the most "senior" programmers are asked to stop
| programming so they can review PRs.
| 8note wrote:
| > You can't "test" comments.
|
| I'm thinking that we're approaching a world where you can both
| test for comments and test the comments themselves.
| senderista wrote:
| Now that would be really interesting: prompt an LLM to find
| comments that misrepresent the code! I wonder how many false
| positives that would bring up?
| ccosky wrote:
| I have a Claude Code skill for adding, deleting and
| improving comments. It does a decent job at detecting when
| comments are out of date with the code and updating them.
| It's not perfect, but it's something.
| perrygeo wrote:
| Considering LLMs are models of language, investing in the clarity
| of the written word pays off in spades.
|
| I don't know whether "literate programming" per se is required.
| Good names, docstrings, type signatures, strategic comments re:
| "why", a good README, and thoughtfully-designed abstractions are
| enough to establish a solid pattern.
|
| Going full "literate programming" may not be necessary. I'd maybe
| reframe it as a focus on communication. Notebooks, examples,
| scripts and such can go a long way to reinforcing the patterns.
|
| Ultimately that's what it's about: establishing patterns for both
| your human readers and your LLMs to follow.
| crazygringo wrote:
| Yeah, I think what is needed is somewhere between
| docstrings+strategic comments, and literate programming.
|
| Basically, it's incredibly helpful to document the higher-level
| structure of the code, almost like extensive docstrings at the
| file level and subdirectory level and project level.
|
| The problem is that major architectural concepts and decisions
| are often cross-cutting across files and directories, so those
| aren't always the right places. And there's also the question
| of what properly belongs in code files, vs. what belongs in
| design documents, and how to ensure they are kept in sync.
| amelius wrote:
| Also:
|
| "Bad programmers worry about the code. Good programmers worry
| about data structures and their relationships."
|
| -- Linus Torvalds
| Swizec wrote:
| > "Bad programmers worry about the code. Good programmers
| worry about data structures and their relationships."
|
| If you get the architecture wrong, everyone complains. If
| you get it right, nobody notices it's there.
| esafak wrote:
| The SRE's Lament.
| rustybolt wrote:
| I have noticed a trend recently that some practices (writing a
| decent README or architecture, being precise and unambiguous with
| language, providing context, literate programming) that were
| meant to help humans were not broadly adopted with the argument
| that it's too much effort. But when done to help an LLM instead
| of a human a lot of people suddenly seem to be a lot more
| motivated to put in the effort.
| zdragnar wrote:
| In my years of programming, I find that humans rarely give
| documentation more than a cursory glance up until they have
| specific questions. Then they ask another person if one is
| available rather than read for the answer.
|
| The biggest problem is that humans don't need the documentation
| until they do. I recall one project that extensively used
| docblock style comments. You could open any file in the project
| and find at least one error, either in the natural language or
| the annotations.
|
| If the LLM actually uses the documentation in every task it
| performs- or if it isn't capable of adequate output without it-
| then that's a far better motivation to document than we
| actually ever had for day to day work.
| jpollock wrote:
| Documentation rots a lot more quickly than the code - it
| doesn't need to be correct for the code to work. You are
| usually better off ignoring the comments (even more so the
| design document) and going straight to the code.
| hinkley wrote:
| I maintain you're either grossly misappropriating the time
| and energy of new and junior devs if this is the case on your
| project, or you have gone too long since hiring a new dev and
| your project is stagnating because of it.
|
| New eyes don't have the curse of knowledge. They don't filter
| out the bullshit bits. And one of the advantages of creating
| reusable modules is you get more new eyes on your code
| regularly.
|
| This may also be a place where AI can help. Some of the
| review tools are already calling us out on making the code
| not match the documentation.
| hinkley wrote:
| Paraphrasing an observation I stole many years ago:
|
| A bunch of us thought learning to talk to computers would get
| them out of learning to talk to humans and so they spent 4 of
| the most important years of emotional growth engaging in that,
| only to graduate and discover they are even farther behind
| everyone else in that area.
| gervwyk wrote:
| For me this is where a config layer shines. Develop a decent
| framework and then let the agents spin out the configuration.
|
| This allows a trusted and tested abstraction layer that does not
| shift and makes maintenance easier, while making the code that
| the agents generate easier to review and it also uses much less
| tokens.
|
| So as always, just build better abstractions.
| cyanydeez wrote:
| when do you think we'll get to build real software?
| jauntywundrkind wrote:
| I fully agree. (Seeing how good Figment2 is for layered config
| in rust is wildly eye opening, has been a revelatory
| experience.)
|
| Sometimes what we manage with config is itself processing
| pipelines. A tool like darktable has a series of processing
| steps that are run. Each of those has config, but the outer
| layer is itself a config of those inner configs. And the outer
| layer is a programmable pipeline; it's not that far apart from
| thinking of each user coming in and building their own http
| handler pipeline, making their own bespoke computational flow.
|
| I guess my point is that computation itself is configuration.
| XSLT probably came closest to that sun. But we see similar
| lessons everywhere we look.
| anotheryou wrote:
| but doesn't "the code is documentation" work better for machines?
|
| and don't we have doc-blocks?
| zdragnar wrote:
| Code doesn't express intent, only the implementation. Docblocks
| are fine for specifying local behavior, but are terrible for
| big picture things.
| anotheryou wrote:
| right you are :)
|
| does literate code have a place for big pic though?
| librasteve wrote:
| I dont know Org, but Rakudoc https://docs.raku.org/language/pod
| is useful for literate programming (put the docs in the code
| source) and for LLM (the code is "self documenting" so that in
| the LLM inversion of control, the LLM can determine how to call
| the code).
|
| https://podlite.org is this done in a language neutral way perl,
| JS/TS and raku for now.
|
| Heres an example: #!/usr/bin/env raku
| =begin pod =head1 NAME Stats::Simple - Simple
| statistical utilities written in Raku =head1 SYNOPSIS
| use Stats::Simple; my @numbers = 10, 20, 30, 40;
| say mean(@numbers); # 25 say median(@numbers); #
| 25 =head1 DESCRIPTION This module provides a few
| simple statistical helper functions such as mean and
| median. It is meant as a small example showing how Rakudoc
| documentation can be embedded directly inside Raku source
| code. =end pod unit module Stats::Simple;
| =begin pod =head2 mean mean(@values -->
| Numeric) Returns the arithmetic mean (average) of a
| list of numeric values. =head3 Parameters =over
| 4 =item @values A list of numeric values.
| =back =head3 Example say mean(1, 2, 3, 4);
| # 2.5 =end pod sub mean(*@values --> Numeric) is
| export { die "No values supplied" if @values.elems ==
| 0; @values.sum / @values.elems; }
| =begin pod =head2 median median(@values -->
| Numeric) Returns the median value of a list of
| numbers. If the list length is even, the function
| returns the mean of the two middle values.
| =head3 Example say median(1, 5, 3); # 3
| say median(1, 2, 3, 4); # 2.5 =end pod sub
| median(*@values --> Numeric) is export { die "No values
| supplied" if @values.elems == 0; my @sorted =
| @values.sort; my $n = @sorted.elems;
| return @sorted[$n div 2] if $n % 2; (@sorted[$n/2
| - 1] + @sorted[$n/2]) / 2; } =begin pod
| =head1 AUTHOR Example written to demonstrate Rakudoc usage.
| =head1 LICENSE Public domain / example code. =end pod
| cadamsdotcom wrote:
| Test code and production code in a symmetrical pair has lots of
| benefits. It's a bit like double entry accounting - you can view
| the code's behavior through a lens of the code itself, or the
| code that proves it does what it seems to do.
|
| You can change the code by changing either tests or production
| code, and letting the other follow.
|
| Code reviews are a breeze because if you're confused by the
| production code, the test code often holds an explanation - and
| vice versa. So just switch from one to the other as needed.
|
| Lots of benefits. The downside is how much extra code you end up
| with of course - up to you if the gains in readability make up
| for it.
| senderista wrote:
| The "test runbook" approach that TFA describes sounds like
| doctest comments in Python or Rust.
| stephbook wrote:
| Take it to the logical conclusion. Track the intended behavior in
| a proper issue tracking software like Jira. Reference the ticket
| in your version control system.
|
| Boring and reliable, I know.
|
| If you need guides to the code base beyond what the programming
| language provides, just write a directory level readme.md where
| necessary.
| andyferris wrote:
| I think the externality of issue tracking systems like Jira (or
| even GitHub) cause friction. Literate programming has
| everything in one place.
|
| I'd like to have a good issue tracking system inside git. I
| think the SQLite version management system has this
| functionality but I never used it.
|
| One thing to solve is that different kinds of users need to
| interact with it in different kinds of ways. Non-programmers
| can use Jira, for example. Issues are often treated as mutable
| text boxes rather than versioned specification (and git is
| designed for the latter). It's tricky!
| jauntywundrkind wrote:
| One of the things I love most about WebMCP is the idea that it's
| a MCP session that exists on the page, which the user already
| knows.
|
| Most of these LLM things are kind of separate systems, with their
| own UI. The idea of agency being inlayed to existing systems the
| user knows like this, with immediate bidirectional feedback as
| the user and LLM work the page, is incredibly incredibly
| compelling to me.
|
| Series of submissions (descending in time):
| https://news.ycombinator.com/item?id=47211249
| https://news.ycombinator.com/item?id=47037501
| https://news.ycombinator.com/item?id=45622604
| jph00 wrote:
| Nearly all my coding for the last decade or so has used literate
| programming. I built nbdev, which has let me write, document, and
| test my software using notebooks. Over the last couple of years
| we integrated LLMs with notebooks and nbdev to create Solveit,
| which everyone at our company uses for nearly all our work (even
| our lawyers, HR, etc).
|
| It turns out literate programming is useful for a lot more than
| just programming!
| amelius wrote:
| We need an append-only programming language.
| cfiggers wrote:
| Interesting and semi-related idea: use LLMs to flag when
| comments/docs have come out of sync with the code.
|
| The big problem with documentation is that _if_ it was accurate
| when it was written, it 's just a matter of time before it goes
| stale compared to the code it's documenting. And while compilers
| can tell you if your types and your implementation have come out
| of sync, before now there's been nothing automated that can check
| whether your comments are still telling the truth.
|
| Somebody could make a startup out of this.
| spawarotti wrote:
| There is at least one startup doing it already (I'm not
| affiliated with it in any way): https://promptless.ai/
| esafak wrote:
| If you have CI hooked up to AI you could you just use a SLM to
| do that in a periodic job with https://github.github.com/gh-aw/
| or https://www.continue.dev/. You could also have it detect
| architectural drift.
| andyhasit wrote:
| I once had a mad idea of creating an automated documentation-
| driven paradigm where every directory/module/class/function has
| to have a DocString/JSDoc, with the higher level ones
| (directory/module) essentially being the documentation of
| features and architecture. A ticket starts by someone opening a
| PR with suggested changes to the docs, the idea being that a
| non-technical person like a PM or tester could do it. The PR
| then passes to a dev who changes the code to match the doc
| changes. Before merging, the tool shows the doc next to every
| modified piece of code and the reviewer must explicitly check a
| box to say it's still valid. And docstrings would be able to
| link to other docstrings, so you could find out what other bits
| of code are connected to what you're working on (as that link
| doesn't always exist in code, e.g. across APIs) and read their
| docs to find the larger context and gotchas.
| kaycebasques wrote:
| I'm a technical writer. Off the top of my head I reckon at
| least 10 startups have ... started up ... in this space since
| 2023.
| amelius wrote:
| Why would you need comments from an AI if you can just ask it
| what the code is doing?
| charcircuit wrote:
| >I don't have data to support this
|
| With there being data that shows context files which explain code
| reduces the performance of them, it is not straightforward that
| literate programming is better so without data this article is
| useless.
___________________________________________________________________
(page generated 2026-03-08 23:00 UTC)