I’ll reformat the comments in my follow up patches to be more concise. Already adopted Ste simplified english in my next patch which adds support for collections. Not a problem.
Jon On Tue, Aug 25, 2026 at 7:20 AM Benedict Elliott Smith <[email protected]> wrote: > I think it's more important than being grating: it lowers (significantly) > the signal:noise ratio of the code, making it harder to work with and > reducing the quality of the codebase over time. It's not just that it's > verbose and badly written, it's that the majority of the contents are not > important to an educated reader. Since we all have access to LLMs to help > us become educated readers of any new section of the codebase, such > comments now offer only negative utility. > > Like Aleksey, I am not discussing any particular patch, only the general > problem of AI generated documentation (at least, without deliberate effort > to ensure this doesn't happen). > > On 2026/08/25 09:56:01 Aleksey Yeshchenko wrote: > > 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. ] > > >> > > > > >
