Many folks find obviously AI-written prose grating. Truly grating. I am one of them, and I know many others who also do.
Anecdotally, a recent discussion on the orange website: https://news.ycombinator.com/item?id=49386699 I don’t think it’s too much to ask from a patch author to edit the comments in their patch to make them non-grating to read for what I estimate is a significant proportion of Cassandra developers. You can have a PR which is unarguably a great improvement *and* has comments that aren’t grating to read. In what world do we have to choose one or the other? Please don’t normalise anti-social behaviour. P.S. In this email and in the previous one I’m not talking about any particular PR. > On 24 Aug 2026, at 18:34, Chris Lohfink <[email protected]> wrote: > > I'd argue it (ai documentation) is normal now. The contents of the PR in > question too is unarguably a great improvement. They worked with the original > authors and were reviewed by multiple committers. I mean, 2x improvement > while fixing data corruption issues? Awesome. > > I like the idea of providing skills or tooling to help create better comments > and understandable comments. It could help with our massive backlog of > spelling errors, bad grammar, and inaccurate comments too. If a comment is > unclear, verbose, inaccurate, or inconsistent with the surrounding code, we > should fix it. That standard should be exactly the same whether the comment > came from an LLM, an IDE completion, copied documentation, or somebody typing > it by hand at 2 AM. I don't think anyone would be against a PR that improves > the comments in this code or would be opposed to an AGENTS change. So I am a > little confused as to why this thread even exists in this form. It seems more > like criticism of how the work was produced, and in places an attempt to > shame the author for using AI. > > I don't think seeing a phrase thats verbose means we should infer that the > author "didn't care enough," "wasn't involved that much in the rest of the > patch," or probably allowed implementation quality to suffer. That is a > pretty large leap from a writing-style preference, especially for a patch > that went through review and produced objectively good results. > > I would be supportive of establishing clearer documentation conventions and > adding tooling to help enforce them. I am much less comfortable with turning > recognizable AI phrasing into evidence about how much effort an author put > into a contribution, or the quality of code that has already been reviewed on > its merits. > > Chris > > On Mon, Aug 24, 2026 at 10:40 AM Aleksey Yeshchenko <[email protected] > <mailto:[email protected]>> wrote: >> This isn’t normal and shouldn’t be tolerated. >> >> Leaving obviously machine-generated commentary (which is never a compliment >> to the prose) in without edits is akin to not fully reviewing LLM-generated >> code. >> >> The moment I see one of these "load-bearing seams” I immediately assume that >> the author didn’t care enough to put in the work to make the prose >> human-readable, >> and probably wasn’t involved that much in the rest of the patch either, >> likely allowing in similar or worse badness in implementation quality. >> >> > On 24 Aug 2026, at 10:55, Mick <[email protected] <mailto:[email protected]>> >> > wrote: >> > >> > Thanks for bringing this up Scott. >> > >> > A big +1 >> > Anything that moves readers into "skim" mode is going to be detrimental to >> > the project in the long term. >> > >> > On top of the existing review skills in trunk, I've been having luck apply >> > the following to my patches: >> > >> > - Shorten (make succint) comments. Cassandra's code style is concise. >> > Comments are not needed for what can easily be read from the code. >> > >> > I also have user defined output-style that, among other things, defines: >> > >> > * Use ASD-STE100 Simplified Technical English, see below: write all >> > responses in STE: short sentences, active voice, one instruction each. >> > * Expand an acronym on first use in a document, then use the bare form. >> > * Avoid Negative parallelisms: "It's not X, it's Y." As in: "It's not a >> > product launch. It's a paradigm shift." This is rhetorical construction, >> > and is rarely of value. >> > * Avoid Rule of threes: "Innovative, transformative, and groundbreaking." >> > Avoid defaulting to triplets when listing anything: adjectives, benefits, >> > takeaways. >> > * Avoid False ranges: "From intimate gatherings to global movements." >> > "From technical expertise to creative vision." The structure implies a >> > spectrum, but there's no actual spectrum. These are just loosely related >> > things dressed up to sound comprehensive. >> > * Avoid Compulsive summaries: "Overall," " In conclusion". I.e, the >> > tendency to restate what was just said, even when the passage is too short >> > to require it. >> > >> > The last four are well known, but sharing here for propersity. (I don't >> > take credit for applying ASD-STE100, but i love it.) >> > >> > Examples of these in use (i haven't manually edited any of the >> > comments/docs here): >> > - https://github.com/apache/cassandra-sidecar/pull/379/changes >> > - https://github.com/apache/cassandra-analytics/pull/236/changes >> > >> > >> > >> > On Sun, 23 Aug 2026, at 2:01 AM, [email protected] >> > <mailto:[email protected]> wrote: >> >> Hi all, >> >> >> >> Anthropic’s current models are famous for generating overwrought >> >> metaphorical constructions like “the load-bearing seam” when referring >> >> to something as simple as an interface. r/ClaudeAI has dubbed this >> >> manner of speaking “Claudish.” Many users (including myself) have >> >> elaborate user prompts that try to tame the model, while others go as >> >> far as passing Opus/Fable-generated output through a competitor’s model >> >> to untangle it. >> >> >> >> Like many, I find reading Claudish grating and artificial - like the >> >> taste of a Sweet ’N Low packet (aspartame), or listening to a 48kbps >> >> MP3 dominated by compression artifacts. >> >> >> >> I’d like to start a discussion about project norms regarding >> >> model-generated comments and documentation in our codebase, largely >> >> prompted by the merge of CASSANDRA-21462 (5b34068). >> >> >> >> I open with my gratitude for work to validate and harden cursor-based >> >> compaction. My local measurements land it between 1.7 - 2.4x the >> >> throughput of legacy iterator-based compaction – a stunning improvement >> >> that will make Cassandra faster and more stable. I also appreciate the >> >> focus on correctness and validation in this work, as it surfaced and >> >> resolved several serious issues. >> >> >> >> The concern it prompts for me is that the commit marks the first >> >> introduction of Claudish into the codebase, and quite a lot of it. >> >> >> >> Examples in the first 1/3 of the patch include: >> >> >> >> – The zero case is load-bearing rather than an optimisation >> >> – The seam is EVENT-shaped because {@link UnfilteredDescriptor}s are >> >> transient >> >> – The row-side analogue of cell reconciliation, is load-bearing in the >> >> cursor's row >> >> – A decoder defect is as likely as on-disk damage here, but that's the >> >> same ambiguity >> >> – The mirror has already drifted from the upstream serializer once >> >> _ The precondition is asserted rather than assumed >> >> – The cursor compaction path and the reference path reach one decision. >> >> They did not always: the cursor carried a hand-mirrored copy >> >> >> >> The linguistic style of Anthropic’s models is sharply out of step with >> >> comments in Cassandra’s codebase. Our comments are concise, flat, and >> >> matter-of-fact. Anthropic’s are littered with literary devices, >> >> metaphors, dependent clauses, adverbs, and read like a detective novel. >> >> They are also very verbose – unsurprising given they bill by the token. >> >> >> >> I’d like to propose a norm for how we approach comments and >> >> documentation in the codebase. The proposal is that all comments and >> >> documentation should maintain our flat and neutral tone, and read as >> >> indistinguishable from human committer authorship. I’d like for us to >> >> normalize watching for this in review as well to maintain the quality >> >> of our in-tree documentation. >> >> >> >> I’d also like to propose removing the Claudish in CASSANDRA-21462 and >> >> replacing it with comments and documentation that are in step with how >> >> we write. >> >> >> >> Interested in others’ thoughts on this. >> >> >> >> – Scott >> >> >> >> [ This thread’s topic is limited to literary style in comments and >> >> documentation. If there are other topics related to model authorship or >> >> the patch above, please discuss them on a separate thread. ] >>
