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]> 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]> 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] 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. ] > >
