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