I’ve noticed that when Claude writes
about
code, it slips into a style where it seems to constantly accrue new jargon. e.g. here’s some terrible documentation that Claude produced (emphasis mine)
The list
arrives straight from
the GraphQL columns argument
, which is [] with no server-side validation, and
the caller
also passes
the synthetic aggregation categories
(aggregations_min/max) that it derives from
stored summary_metrics fields
rather than reading here. Both are why this allowlists against
the column Enum8
instead of rejecting
known-bad names
: an unrecognized value in a
per-branch column = u /col_N
is a
hard UNKNOWN_ELEMENT_OF_ENUM (code 691)
that fails
the whole read
, where
the set membership
it replaced just matched nothing.
The bolded text is my attempt to highlight concepts that the text assumes the reader already understands and currently has in their head. Some of these are reasonable:
basic comp-sci concepts like “the caller” (this is a function docstring; it’s pretty obvious which “caller” the comment refers to)
“summary_metrics fields” – while opaque out of context, this is a really important business-logic construct in our app that any developer reviewing this code would be familiar with
It seems like Claude has no natural sense of hierarchy or abstraction. Giving more detail and more context often makes documentation
worse
by distracting the reader from the core idea you’re trying to communicate, because every unrecognized concept is something that a thorough reader will feel the need to look up. Who knows: maybe I
need
to know what a
hard UNKNOWN_ELEMENT_OF_ENUM (code 691)
is to understand the purpose of this function.
I can kind of imagine why it would end up this way, just from my layman’s understanding of how attention/transformers work – if you’re optimizing for output that other agents understand quickly, it probably helps to drop a bunch of “pointers” in the text that direct the attention of the model back toward a bunch of related concepts. It seems like frontier models’ working memory is just big enough that this is useful rather than distracting.
Humans don’t have that much working memory, though. Or I don’t, at any rate. And the comments are ostensibly for both me
and
future agents to read, so it kind of sucks that they’re written only for the latter. Have any of you successfully gotten Claude to exercise some judgment about which concepts are important (or even
load-bearing
🙄) and which ones are better left out?
submitted by
/u/ForSpareParts
Originally posted by u/ForSpareParts on r/ClaudeCode