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