Thank you for bringing this up! My 2 cents would be, when we review comments/documentation, the questions we ask ourselves should be: 1. Is it correct? 2. Is it clear? 3. Is it concise? And any other good qualities we have been looking for in documentation since pre-AI time.
But not “does it look like AI-generated?” If the AI-generated doc is in good quality, what’s the problem? So, I agree that we should use the word API instead of “the load bearing seam”, cuz it’s not clear. I also agree that we should get rid of the verbose comments, cuz they are not concise. But I don’t think we need to bother to make it looks human-written, like getting rid of the dash - as long as it’s still correct, clear, and concise. Jane On Sun, Aug 23, 2026 at 11:45 Chris Lohfink <[email protected]> wrote: > I guess I have a bit of the opposite view. After years of no comments > and vague documentation we have correct albeit verbose PRs coming up. While > I think it's perfectly acceptable to create PRs or make recommendations > that do things like make comments more readable, I am -1 to the idea of > restricting or having requirements verbiage to being a nebulous "better". I > think that also leads to a path that can discriminate against non native > speakers for difficult to understand English in their commits. > > Chris > > On Sun, Aug 23, 2026 at 1:35 PM David Capwell <[email protected]> wrote: > >> Maybe a native speaker can quickly digest and filter out all witticisms, >> but for folks like me it might be challenging. >> >> >> We can’t… there is a reason that 2 skill patterns have taken hold: speak >> to me like i’m 5, and asd-ste100… in short it’s word vomit that no one >> understands. What’s worse is that trying to understand it confuses humans >> and Claude; leading to worse outputs than if the comments were just thrown >> away. >> >> >> Sent from my iPhone >> >> On Aug 23, 2026, at 6:23 AM, Alex Petrov <[email protected]> wrote: >> >> >> Thank you for bringing the subject of LLM-generated prose. I'd like to >> first mention that I only had a cursory glance at 21452/21462, and my >> comment is about LLM-generated prose in general rather than this patch in >> particular. >> >> My recent impression after reading an LLM-generated README in an OSS >> project (albeit not in Cassandra) was the feeling that I have started >> reading mid-paragraph, and the writing itself was witty and confusing, >> which ultimately lead me to closing the browser window rather than >> bothering to digest that text. >> >> I tend to remove all LLM-generated comments from my own code. For me, >> clarity goes beyond comments in code: any artefact that another human is >> going to read (for example, a code-review post, or bug >> analysis/investigation), needs to pass a readability bar. Having that said, >> I hate to admit that my own writing style might have also changed for worse >> over the course of this year. >> >> An additional reason (besides consistency with our existing comments and >> documentation) for having simpler language in documentation and code is the >> fact that for many of us English is not a first (and for some, not even a >> second) language. Maybe a native speaker can quickly digest and filter out >> all witticisms, but for folks like me it might be challenging. >> >> +1 for simplifying the language for both AI- and human generated prose. >> >> >> On Sun, Aug 23, 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. ] >> >> >> >>
