+1 to the suggestion of ASD-STE100. I have a similar writing style guide encoded in a markdown to what Mick describes and I've noticed it helps with LLM comments a lot.
On Mon, Aug 24, 2026 at 5:56 AM 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. ] >
