Hello Devs,
Given the use of AI has increased recently I think this deserves discussion.
There are certain texts that are, ultimately, transient, or read less
frequently as time moves on.
This broadly includes tickets, which generally become mostly irrelevant
once resolved.
While reading AI tickets can be exhausting, I'm willing, within reason,
to accept them as a fact of live.
But there are parts of the code base in which we have prose that is
written once and read
often. I'm primarily concerned with Notes, Commit messages, and to a
lesser degree code comments.
I've noticed more people have been posting LLM generated bug fixes
(fine, it's policy) where
seemingly little work went into polishing texts other devs will read
many times. I consider this a problem.
I think it's important for certain parts of the code base to be written
concisely. Something LLMs
are terrible at today, and even skills make it marginally better. This
is just a fact.
I think especially with the release of Opus 5.5 this has become *more*
of an issue as the prose is
now only bad in a myriad ways that are not immediately obvious rather
than being obviously atrocious at a glance.
Which leads people to take it as-is without putting effort into writing
it by hand, or at least trimming it down after the fact.
This is obviously bad for human consumers of these texts. But even if
you are "all in" on AI these texts
are also objectively garbage for future AI use as they are bloated with
irrelevant facts, meaningless past
history, repeating things obvious from context and generally wordy for
no benefit.
They are simply bad.
Is it fair to expect people to put in more effort into these? I think yes.
Notes are *the* way to understand the code base. And making them worse
permanently
degrades the ability of newcomers to understand the codebase. Similarly
commit messages
are hugely important to be able to determine when changes where
introduced, quickly find
ranges of commits to bisect for new bugs and many more regular
maintenance tasks.
*My plan is to aggressively request improvement of prose during MR
review going forward.*
Accepting bad prose is worse for maintainers because they have to read
texts three times to understand what is going on.
It's worse for agents because it fills context windows with irrelevant
facts and pointless trivia that poison their
reasoning ability.
It's just worse, and it takes little effort to fix.
But maybe I'm alone in feeling this way. If everyone else is happy to
read Opus text output all, or at least to have opus read opus
output all day long. Then I will surrender this fight and move to
another hill to die on.
But if people are feeling similarly then please let me know and do likewise.
I don't think it's a big ask either. If you are prompting already just
type a draft in your commit message/note and let claude do
formatting/typo/alignment fixes. A sloppy text pushed through claude
will in most cases beat what any model today
will generate on it's own. Maybe this changes in 2 years. But it's not
changing today.
It's not just a question of length. You can make a LLM generate shorter
texts with a skill file or otherwise.
But they are terrible at understanding what the tricky parts are, what
is worth highlighting, what can
be dropped because it is obvious from wider context.
I think it's *easy* for every contributor who knows what is happening in
their patch to reach a reasonable standard.
But we have to ask them to do it and to set the expectation. And I hope
we can do so.
Andreas,
freshly back from reading some claude output.
_______________________________________________
ghc-devs mailing list -- [email protected]
To unsubscribe send an email to [email protected]
