+1 on the effort of trying to codify comments standards for the project. I don’t think it can harm, and having human readable rules (even if they are in agents.md) will help both agent and humans to produce meaningful concise comments.
> El ago 27, 2026, a las 6:10 a.m., Jaydeep Chovatia > <[email protected]> escribió: > > +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] > <mailto:[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] >> <mailto:[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] >>> > > <mailto:[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]> <mailto:[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]> <mailto:[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]> <mailto:[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. ] >>> > >> >>> > >>> >
