+1. AI can help us write, but human editing shouldn't be skipped. Requiring clear, simple comments before merging makes a lot of sense.
Jaydeep On Tue, Aug 25, 2026 at 8:27 AM Jon Haddad <[email protected]> wrote: > 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. ] >> > >> >> > >> > >> >
