[DISCUSS] The Load-Bearing Seam

[sc...@paradoxica.net]

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

Re: [DISCUSS] The Load-Bearing Seam

[David Capwell <dc...@apple.com>]

I agree that comments can be good so banning isn’t the best but bad comments
hurt more than no comments for me

  

But we know this is a AI problem so we can try to improve this with skills /
Claude.md

  

[![plugins.png](cid:5AAB40D6-4F13-4CAE-A247-1AA8EA32AA35)  
---  
| [plugins/pstack/skills/unslop/SKILL.md at main ·
cursor/plugins](https://github.com/cursor/plugins/blob/main/pstack/skills/unslop/SKILL.md)[github.com](https://github.com/cursor/plugins/blob/main/pstack/skills/unslop/SKILL.md)  
---  
](https://github.com/cursor/plugins/blob/main/pstack/skills/unslop/SKILL.md)

  

Skills like this are common so we can always try to improve rather than
reject. Opus loves to add comments that are obvious so can always try to guide
it not to.  We can create agents that only do doc review and have our
Claude.md ask to create sub agents specifically to review the comments…

  

  

Sent from my iPhone

  

> On Aug 23, 2026, at 11:51 AM, Chris Lohfink <cl...@gmail.com> 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
> <[dcapwell@apple.com](mailto:dcapwell@apple.com)> 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
<[alexp@coffeenco.de](mailto:alexp@coffeenco.de)> 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,
[scott@paradoxica.net](mailto:scott@paradoxica.net) 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. ]

>>>>

>>>>  
>
>>>>

>>>>  
>
>>>

>>>  
>

Re: [DISCUSS] The Load-Bearing Seam

[Josh McKenzie <jm...@apache.org>]

+1 to defining a skill in-repo or modifying AGENTS.md to include constraints to try and get some more terseness out of the models. I agree strongly w/Chris' point that we have a lot of code that's effectively not commented; if I had to zero sum pick between no comments on opaque code or Claudish, I'd hold my nose and take the latter any day.

Ideally we'll find something in the middle with comments explaining *why* we're doing things that are non-obvious with a minimal amount of "honest load-bearing seams" scattered about. Whatever the peculiarities of the writing styles are today they're just going to drift so better we prescribe how we want things to look to provide a little consistency as the space continues to evolve.

On Sun, Aug 23, 2026, at 3:58 PM, Ekaterina Dimitrova wrote:
> I love this conversation.
> 
> Below is what I think and I talk in general, I haven’t looked at the particular PR mentioned.
> 
> I think adding a skill around writing docs/comments and actually settling on some directions about what we aim for as a community, so new people can also learn quickly, not just by vibes, reading around - sounds great. Thanks David, for bringing it 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?”
> 
> I agree on this. I catch myself cutting/editing a lot of AI-generated docs/comments for good reasons stated here. But also, as a non-native speaker, I love how AI can quickly improve my writing, my grammar. 
> And I wanted to mention - sometimes I ask it to improve what I wrote, then it feels a bit different style than the one I would use, but it is still accurate and makes sense - then I leave it as is but I also stress even more for others that AI helped, especially with the writing, but I verified it and I fixed it. It is different but verified and good, so I’d say it serves the needs of documenting more, which Chris mentioned we were missing a lot in time. 
> There is also the psychological element - we all don’t want to allow slop, so the moment we see something that doesn’t sound exactly as the person who submitted it, many times a red lamp turns on, and we catch ourselves wondering how much the person who submitted it looked into it etc., but that doesn’t mean the submission is immediately bad.
> 
> *This email was fully Ekaterina-written. :-) (I am sure there are some grammar mistakes to prove it)*
> 
> On Sun, 23 Aug 2026 at 15:17, Jane H <ja...@apache.org> wrote:
>> 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 <cl...@gmail.com> 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 <dc...@apple.com> 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 <al...@coffeenco.de> 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, scott@paradoxica.net 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. ]
>>>>>> 
>>>>>> 
>>>>> 

Re: [DISCUSS] The Load-Bearing Seam

[Ekaterina Dimitrova <e....@gmail.com>]

I love this conversation.

Below is what I think and I talk in general, I haven’t looked at the
particular PR mentioned.

I think adding a skill around writing docs/comments and actually settling
on some directions about what we aim for as a community, so new people can
also learn quickly, not just by vibes, reading around - sounds great.
Thanks David, for bringing it 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?”

I agree on this. I catch myself cutting/editing a lot of AI-generated
docs/comments for good reasons stated here. But also, as a non-native
speaker, I love how AI can quickly improve my writing, my grammar.
And I wanted to mention - sometimes I ask it to improve what I wrote, then
it feels a bit different style than the one I would use, but it is still
accurate and makes sense - then I leave it as is but I also stress even
more for others that AI helped, especially with the writing, but I verified
it and I fixed it. It is different but verified and good, so I’d say it
serves the needs of documenting more, which Chris mentioned we were missing
a lot in time.
There is also the psychological element - we all don’t want to allow slop,
so the moment we see something that doesn’t sound exactly as the person who
submitted it, many times a red lamp turns on, and we catch ourselves
wondering how much the person who submitted it looked into it etc., but
that doesn’t mean the submission is immediately bad.

*This email was fully Ekaterina-written. :-) (I am sure there are some
grammar mistakes to prove it)*

On Sun, 23 Aug 2026 at 15:17, Jane H <ja...@apache.org> wrote:

> 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 <cl...@gmail.com> 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 <dc...@apple.com> 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 <al...@coffeenco.de> 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, scott@paradoxica.net 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. ]
>>>
>>>
>>>
>>>

Re: [DISCUSS] The Load-Bearing Seam

[Jane H <ja...@apache.org>]

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 <cl...@gmail.com> 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 <dc...@apple.com> 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 <al...@coffeenco.de> 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, scott@paradoxica.net 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. ]
>>
>>
>>
>>

Re: [DISCUSS] The Load-Bearing Seam

[Chris Lohfink <cl...@gmail.com>]

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 <dc...@apple.com> 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 <al...@coffeenco.de> 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, scott@paradoxica.net 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. ]
>
>
>
>

Re: [DISCUSS] The Load-Bearing Seam

[David Capwell <dc...@apple.com>]

> 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 <al...@coffeenco.de> 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,
> [scott@paradoxica.net](mailto:scott@paradoxica.net) 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. ]

>>

>>  
>
>>

>>  
>
>
>  
>

Re: [DISCUSS] The Load-Bearing Seam

[Alex Petrov <al...@coffeenco.de>]

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, scott@paradoxica.net 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. ]
> 
> 

Re: [DISCUSS] The Load-Bearing Seam

[Isaac Reath <is...@gmail.com>]

+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 <mc...@apache.org> 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, scott@paradoxica.net 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. ]
>

Re: [DISCUSS] The Load-Bearing Seam

[Bernardo Botella <co...@bernardobotella.com>]

+1 on the effort of trying to codify comments standards for the project. I don’t think it can harm, and having human readable rules (even if they are in agents.md) will help both agent and humans to produce meaningful concise comments.

> El ago 27, 2026, a las 6:10 a.m., Jaydeep Chovatia <ch...@gmail.com> escribió:
> 
> +1. AI can help us write, but human editing shouldn't be skipped. Requiring clear, simple comments before merging makes a lot of sense.
> 
> Jaydeep
> 
> On Tue, Aug 25, 2026 at 8:27 AM Jon Haddad <jon@rustyrazorblade.com <ma...@rustyrazorblade.com>> wrote:
>> I’ll reformat the comments in my follow up patches to be more concise. Already adopted Ste simplified english in my next patch which adds support for collections. Not a problem. 
>> 
>> Jon
>> 
>> On Tue, Aug 25, 2026 at 7:20 AM Benedict Elliott Smith <benedict@apache.org <ma...@apache.org>> wrote:
>>> I think it's more important than being grating: it lowers (significantly) the signal:noise ratio of the code, making it harder to work with and reducing the quality of the codebase over time. It's not just that it's verbose and badly written, it's that the majority of the contents are not important to an educated reader. Since we all have access to LLMs to help us become educated readers of any new section of the codebase, such comments now offer only negative utility.
>>> 
>>> Like Aleksey, I am not discussing any particular patch, only the general problem of AI generated documentation (at least, without deliberate effort to ensure this doesn't happen).
>>> 
>>> On 2026/08/25 09:56:01 Aleksey Yeshchenko wrote:
>>> > Many folks find obviously AI-written prose grating. Truly grating. I am one of them, and I know many others who also do.
>>> > 
>>> > Anecdotally, a recent discussion on the orange website: https://news.ycombinator.com/item?id=49386699
>>> > 
>>> > I don’t think it’s too much to ask from a patch author to edit the comments in their patch to make them non-grating to read for what I estimate is a significant proportion of Cassandra developers.
>>> > 
>>> > You can have a PR which is unarguably a great improvement *and* has comments that aren’t grating to read. In what world do we have to choose one or the other?
>>> > 
>>> > Please don’t normalise anti-social behaviour.
>>> > 
>>> > P.S. In this email and in the previous one I’m not talking about any particular PR.
>>> > 
>>> > > On 24 Aug 2026, at 18:34, Chris Lohfink <clohfink85@gmail.com <ma...@gmail.com>> wrote:
>>> > > 
>>> > > I'd argue it (ai documentation) is normal now. The contents of the PR in question too is unarguably a great improvement. They worked with the original authors and were reviewed by multiple committers. I mean, 2x improvement while fixing data corruption issues? Awesome.
>>> > > 
>>> > > I like the idea of providing skills or tooling to help create better comments and understandable comments. It could help with our massive backlog of spelling errors, bad grammar, and inaccurate comments too. If a comment is unclear, verbose, inaccurate, or inconsistent with the surrounding code, we should fix it. That standard should be exactly the same whether the comment came from an LLM, an IDE completion, copied documentation, or somebody typing it by hand at 2 AM. I don't think anyone would be against a PR that improves the comments in this code or would be opposed to an AGENTS change. So I am a little confused as to why this thread even exists in this form. It seems more like criticism of how the work was produced, and in places an attempt to shame the author for using AI.
>>> > > 
>>> > > I don't think seeing a phrase thats verbose means we should infer that the author "didn't care enough," "wasn't involved that much in the rest of the patch," or probably allowed implementation quality to suffer. That is a pretty large leap from a writing-style preference, especially for a patch that went through review and produced objectively good results.
>>> > > 
>>> > > I would be supportive of establishing clearer documentation conventions and adding tooling to help enforce them. I am much less comfortable with turning recognizable AI phrasing into evidence about how much effort an author put into a contribution, or the quality of code that has already been reviewed on its merits.
>>> > > 
>>> > > Chris
>>> > > 
>>> > > On Mon, Aug 24, 2026 at 10:40 AM Aleksey Yeshchenko <aleksey@apple.com <ma...@apple.com> <mailto:aleksey@apple.com <ma...@apple.com>>> wrote:
>>> > >> 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 <mck@apache.org <ma...@apache.org> <mailto:mck@apache.org <ma...@apache.org>>> 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, scott@paradoxica.net <ma...@paradoxica.net> <mailto:scott@paradoxica.net <ma...@paradoxica.net>> 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. ]
>>> > >> 
>>> > 
>>> >

Re: [DISCUSS] The Load-Bearing Seam

[Jaydeep Chovatia <ch...@gmail.com>]

+1. AI can help us write, but human editing shouldn't be skipped. Requiring
clear, simple comments before merging makes a lot of sense.

Jaydeep

On Tue, Aug 25, 2026 at 8:27 AM Jon Haddad <jo...@rustyrazorblade.com> wrote:

> I’ll reformat the comments in my follow up patches to be more concise.
> Already adopted Ste simplified english in my next patch which adds support
> for collections. Not a problem.
>
> Jon
>
> On Tue, Aug 25, 2026 at 7:20 AM Benedict Elliott Smith <
> benedict@apache.org> wrote:
>
>> I think it's more important than being grating: it lowers (significantly)
>> the signal:noise ratio of the code, making it harder to work with and
>> reducing the quality of the codebase over time. It's not just that it's
>> verbose and badly written, it's that the majority of the contents are not
>> important to an educated reader. Since we all have access to LLMs to help
>> us become educated readers of any new section of the codebase, such
>> comments now offer only negative utility.
>>
>> Like Aleksey, I am not discussing any particular patch, only the general
>> problem of AI generated documentation (at least, without deliberate effort
>> to ensure this doesn't happen).
>>
>> On 2026/08/25 09:56:01 Aleksey Yeshchenko wrote:
>> > Many folks find obviously AI-written prose grating. Truly grating. I am
>> one of them, and I know many others who also do.
>> >
>> > Anecdotally, a recent discussion on the orange website:
>> https://news.ycombinator.com/item?id=49386699
>> >
>> > I don’t think it’s too much to ask from a patch author to edit the
>> comments in their patch to make them non-grating to read for what I
>> estimate is a significant proportion of Cassandra developers.
>> >
>> > You can have a PR which is unarguably a great improvement *and* has
>> comments that aren’t grating to read. In what world do we have to choose
>> one or the other?
>> >
>> > Please don’t normalise anti-social behaviour.
>> >
>> > P.S. In this email and in the previous one I’m not talking about any
>> particular PR.
>> >
>> > > On 24 Aug 2026, at 18:34, Chris Lohfink <cl...@gmail.com> wrote:
>> > >
>> > > I'd argue it (ai documentation) is normal now. The contents of the PR
>> in question too is unarguably a great improvement. They worked with the
>> original authors and were reviewed by multiple committers. I mean, 2x
>> improvement while fixing data corruption issues? Awesome.
>> > >
>> > > I like the idea of providing skills or tooling to help create better
>> comments and understandable comments. It could help with our massive
>> backlog of spelling errors, bad grammar, and inaccurate comments too. If a
>> comment is unclear, verbose, inaccurate, or inconsistent with the
>> surrounding code, we should fix it. That standard should be exactly the
>> same whether the comment came from an LLM, an IDE completion, copied
>> documentation, or somebody typing it by hand at 2 AM. I don't think anyone
>> would be against a PR that improves the comments in this code or would be
>> opposed to an AGENTS change. So I am a little confused as to why this
>> thread even exists in this form. It seems more like criticism of how the
>> work was produced, and in places an attempt to shame the author for using
>> AI.
>> > >
>> > > I don't think seeing a phrase thats verbose means we should infer
>> that the author "didn't care enough," "wasn't involved that much in the
>> rest of the patch," or probably allowed implementation quality to suffer.
>> That is a pretty large leap from a writing-style preference, especially for
>> a patch that went through review and produced objectively good results.
>> > >
>> > > I would be supportive of establishing clearer documentation
>> conventions and adding tooling to help enforce them. I am much less
>> comfortable with turning recognizable AI phrasing into evidence about how
>> much effort an author put into a contribution, or the quality of code that
>> has already been reviewed on its merits.
>> > >
>> > > Chris
>> > >
>> > > On Mon, Aug 24, 2026 at 10:40 AM Aleksey Yeshchenko <
>> aleksey@apple.com <ma...@apple.com>> wrote:
>> > >> 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 <mck@apache.org <mailto:
>> mck@apache.org>> 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, scott@paradoxica.net <mailto:
>> scott@paradoxica.net> 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. ]
>> > >>
>> >
>> >
>>
>

Re: [DISCUSS] The Load-Bearing Seam

[Jon Haddad <jo...@rustyrazorblade.com>]

I’ll reformat the comments in my follow up patches to be more concise.
Already adopted Ste simplified english in my next patch which adds support
for collections. Not a problem.

Jon

On Tue, Aug 25, 2026 at 7:20 AM Benedict Elliott Smith <be...@apache.org>
wrote:

> I think it's more important than being grating: it lowers (significantly)
> the signal:noise ratio of the code, making it harder to work with and
> reducing the quality of the codebase over time. It's not just that it's
> verbose and badly written, it's that the majority of the contents are not
> important to an educated reader. Since we all have access to LLMs to help
> us become educated readers of any new section of the codebase, such
> comments now offer only negative utility.
>
> Like Aleksey, I am not discussing any particular patch, only the general
> problem of AI generated documentation (at least, without deliberate effort
> to ensure this doesn't happen).
>
> On 2026/08/25 09:56:01 Aleksey Yeshchenko wrote:
> > Many folks find obviously AI-written prose grating. Truly grating. I am
> one of them, and I know many others who also do.
> >
> > Anecdotally, a recent discussion on the orange website:
> https://news.ycombinator.com/item?id=49386699
> >
> > I don’t think it’s too much to ask from a patch author to edit the
> comments in their patch to make them non-grating to read for what I
> estimate is a significant proportion of Cassandra developers.
> >
> > You can have a PR which is unarguably a great improvement *and* has
> comments that aren’t grating to read. In what world do we have to choose
> one or the other?
> >
> > Please don’t normalise anti-social behaviour.
> >
> > P.S. In this email and in the previous one I’m not talking about any
> particular PR.
> >
> > > On 24 Aug 2026, at 18:34, Chris Lohfink <cl...@gmail.com> wrote:
> > >
> > > I'd argue it (ai documentation) is normal now. The contents of the PR
> in question too is unarguably a great improvement. They worked with the
> original authors and were reviewed by multiple committers. I mean, 2x
> improvement while fixing data corruption issues? Awesome.
> > >
> > > I like the idea of providing skills or tooling to help create better
> comments and understandable comments. It could help with our massive
> backlog of spelling errors, bad grammar, and inaccurate comments too. If a
> comment is unclear, verbose, inaccurate, or inconsistent with the
> surrounding code, we should fix it. That standard should be exactly the
> same whether the comment came from an LLM, an IDE completion, copied
> documentation, or somebody typing it by hand at 2 AM. I don't think anyone
> would be against a PR that improves the comments in this code or would be
> opposed to an AGENTS change. So I am a little confused as to why this
> thread even exists in this form. It seems more like criticism of how the
> work was produced, and in places an attempt to shame the author for using
> AI.
> > >
> > > I don't think seeing a phrase thats verbose means we should infer that
> the author "didn't care enough," "wasn't involved that much in the rest of
> the patch," or probably allowed implementation quality to suffer. That is a
> pretty large leap from a writing-style preference, especially for a patch
> that went through review and produced objectively good results.
> > >
> > > I would be supportive of establishing clearer documentation
> conventions and adding tooling to help enforce them. I am much less
> comfortable with turning recognizable AI phrasing into evidence about how
> much effort an author put into a contribution, or the quality of code that
> has already been reviewed on its merits.
> > >
> > > Chris
> > >
> > > On Mon, Aug 24, 2026 at 10:40 AM Aleksey Yeshchenko <aleksey@apple.com
> <ma...@apple.com>> wrote:
> > >> 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 <mck@apache.org <mailto:
> mck@apache.org>> 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, scott@paradoxica.net <mailto:
> scott@paradoxica.net> 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. ]
> > >>
> >
> >
>

Re: [DISCUSS] The Load-Bearing Seam

[Benedict Elliott Smith <be...@apache.org>]

I think it's more important than being grating: it lowers (significantly) the signal:noise ratio of the code, making it harder to work with and reducing the quality of the codebase over time. It's not just that it's verbose and badly written, it's that the majority of the contents are not important to an educated reader. Since we all have access to LLMs to help us become educated readers of any new section of the codebase, such comments now offer only negative utility.

Like Aleksey, I am not discussing any particular patch, only the general problem of AI generated documentation (at least, without deliberate effort to ensure this doesn't happen).

On 2026/08/25 09:56:01 Aleksey Yeshchenko wrote:
> Many folks find obviously AI-written prose grating. Truly grating. I am one of them, and I know many others who also do.
> 
> Anecdotally, a recent discussion on the orange website: https://news.ycombinator.com/item?id=49386699
> 
> I don’t think it’s too much to ask from a patch author to edit the comments in their patch to make them non-grating to read for what I estimate is a significant proportion of Cassandra developers.
> 
> You can have a PR which is unarguably a great improvement *and* has comments that aren’t grating to read. In what world do we have to choose one or the other?
> 
> Please don’t normalise anti-social behaviour.
> 
> P.S. In this email and in the previous one I’m not talking about any particular PR.
> 
> > On 24 Aug 2026, at 18:34, Chris Lohfink <cl...@gmail.com> wrote:
> > 
> > I'd argue it (ai documentation) is normal now. The contents of the PR in question too is unarguably a great improvement. They worked with the original authors and were reviewed by multiple committers. I mean, 2x improvement while fixing data corruption issues? Awesome.
> > 
> > I like the idea of providing skills or tooling to help create better comments and understandable comments. It could help with our massive backlog of spelling errors, bad grammar, and inaccurate comments too. If a comment is unclear, verbose, inaccurate, or inconsistent with the surrounding code, we should fix it. That standard should be exactly the same whether the comment came from an LLM, an IDE completion, copied documentation, or somebody typing it by hand at 2 AM. I don't think anyone would be against a PR that improves the comments in this code or would be opposed to an AGENTS change. So I am a little confused as to why this thread even exists in this form. It seems more like criticism of how the work was produced, and in places an attempt to shame the author for using AI.
> > 
> > I don't think seeing a phrase thats verbose means we should infer that the author "didn't care enough," "wasn't involved that much in the rest of the patch," or probably allowed implementation quality to suffer. That is a pretty large leap from a writing-style preference, especially for a patch that went through review and produced objectively good results.
> > 
> > I would be supportive of establishing clearer documentation conventions and adding tooling to help enforce them. I am much less comfortable with turning recognizable AI phrasing into evidence about how much effort an author put into a contribution, or the quality of code that has already been reviewed on its merits.
> > 
> > Chris
> > 
> > On Mon, Aug 24, 2026 at 10:40 AM Aleksey Yeshchenko <aleksey@apple.com <ma...@apple.com>> wrote:
> >> 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 <mck@apache.org <ma...@apache.org>> 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, scott@paradoxica.net <ma...@paradoxica.net> 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. ]
> >> 
> 
> 

Re: [DISCUSS] The Load-Bearing Seam

[Aleksey Yeshchenko <al...@apple.com>]

Many folks find obviously AI-written prose grating. Truly grating. I am one of them, and I know many others who also do.

Anecdotally, a recent discussion on the orange website: https://news.ycombinator.com/item?id=49386699

I don’t think it’s too much to ask from a patch author to edit the comments in their patch to make them non-grating to read for what I estimate is a significant proportion of Cassandra developers.

You can have a PR which is unarguably a great improvement *and* has comments that aren’t grating to read. In what world do we have to choose one or the other?

Please don’t normalise anti-social behaviour.

P.S. In this email and in the previous one I’m not talking about any particular PR.

> On 24 Aug 2026, at 18:34, Chris Lohfink <cl...@gmail.com> wrote:
> 
> I'd argue it (ai documentation) is normal now. The contents of the PR in question too is unarguably a great improvement. They worked with the original authors and were reviewed by multiple committers. I mean, 2x improvement while fixing data corruption issues? Awesome.
> 
> I like the idea of providing skills or tooling to help create better comments and understandable comments. It could help with our massive backlog of spelling errors, bad grammar, and inaccurate comments too. If a comment is unclear, verbose, inaccurate, or inconsistent with the surrounding code, we should fix it. That standard should be exactly the same whether the comment came from an LLM, an IDE completion, copied documentation, or somebody typing it by hand at 2 AM. I don't think anyone would be against a PR that improves the comments in this code or would be opposed to an AGENTS change. So I am a little confused as to why this thread even exists in this form. It seems more like criticism of how the work was produced, and in places an attempt to shame the author for using AI.
> 
> I don't think seeing a phrase thats verbose means we should infer that the author "didn't care enough," "wasn't involved that much in the rest of the patch," or probably allowed implementation quality to suffer. That is a pretty large leap from a writing-style preference, especially for a patch that went through review and produced objectively good results.
> 
> I would be supportive of establishing clearer documentation conventions and adding tooling to help enforce them. I am much less comfortable with turning recognizable AI phrasing into evidence about how much effort an author put into a contribution, or the quality of code that has already been reviewed on its merits.
> 
> Chris
> 
> On Mon, Aug 24, 2026 at 10:40 AM Aleksey Yeshchenko <aleksey@apple.com <ma...@apple.com>> wrote:
>> 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 <mck@apache.org <ma...@apache.org>> 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, scott@paradoxica.net <ma...@paradoxica.net> 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. ]
>> 

Re: [DISCUSS] The Load-Bearing Seam

[Chris Lohfink <cl...@gmail.com>]

I'd argue it (ai documentation) is normal now. The contents of the PR in
question too is unarguably a great improvement. They worked with the
original authors and were reviewed by multiple committers. I mean, 2x
improvement while fixing data corruption issues? Awesome.

I like the idea of providing skills or tooling to help create better
comments and understandable comments. It could help with our massive
backlog of spelling errors, bad grammar, and inaccurate comments too. If a
comment is unclear, verbose, inaccurate, or inconsistent with the
surrounding code, we should fix it. That standard should be exactly the
same whether the comment came from an LLM, an IDE completion, copied
documentation, or somebody typing it by hand at 2 AM. I don't think anyone
would be against a PR that improves the comments in this code or would be
opposed to an AGENTS change. So I am a little confused as to why this
thread even exists in this form. It seems more like criticism of how the
work was produced, and in places an attempt to shame the author for using
AI.

I don't think seeing a phrase thats verbose means we should infer that the
author "didn't care enough," "wasn't involved that much in the rest of the
patch," or probably allowed implementation quality to suffer. That is a
pretty large leap from a writing-style preference, especially for a patch
that went through review and produced objectively good results.

I would be supportive of establishing clearer documentation conventions and
adding tooling to help enforce them. I am much less comfortable with
turning recognizable AI phrasing into evidence about how much effort an
author put into a contribution, or the quality of code that has already
been reviewed on its merits.

Chris

On Mon, Aug 24, 2026 at 10:40 AM Aleksey Yeshchenko <al...@apple.com>
wrote:

> 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 <mc...@apache.org> 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, scott@paradoxica.net 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. ]
>
>

Re: [DISCUSS] The Load-Bearing Seam

[Aleksey Yeshchenko <al...@apple.com>]

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 <mc...@apache.org> 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, scott@paradoxica.net 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. ]

Re: [DISCUSS] The Load-Bearing Seam

[Mick <mc...@apache.org>]

>  Comments are not needed for what can easily be read from the code.


And a quick retrospective on that^

At first I was strongly suspicuous such an ambiguous instruction would land (who defines "easily" here), but much to my surprise claude has applied it to a T.

Re: [DISCUSS] The Load-Bearing Seam

[Mick <mc...@apache.org>]

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, scott@paradoxica.net 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. ]