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