-
Prefer short sentences. If a sentence has two clauses joined by "so", "because", "but", "even though", "although", or a comma + participle, consider splitting it. Contrastive joiners ("but X", "even though Y") are especially risky when both halves introduce a fact the reader does not already have — pack two new facts into one sentence and the reader stalls. State each rule in its own sentence, then connect them.
-
Avoid stacked abstractions like "left the outer scope advertising the column as X" or "the projection inherits the source's reverseLookup names". Replace with a concrete chain.
-
Avoid compiler/optimizer/execution-engine jargon ("outer reference", "outer scope", "binding context", "name resolution scope", "vector encoding") unless the rest of the paragraph already established it. If you must use it, define it inline with a tiny example.
-
Prefer plain verbs (used, dropped, kept) over jargon verbs (advertise, surface, propagate, materialize) unless the jargon is the precise term.
-
Avoid hyphenated compound-noun stacks ("user-written case", "lookup-based fallback", "context-aware resolver"). They require the reader to unpack a modifier chain before getting to the noun. Rewrite as a relative clause ("the case the user wrote") or a single concrete noun.
-
Prefer the word with one obvious meaning in this context. "Case" can mean legal case, match case, or upper/lower case — use "capitalization" when you mean letter case. Similarly: "operator" vs "function", "key" vs "column", "type" vs "kind" — pick the one a SQL reader and a C++ reader both interpret the same way.
-
Show a complete example query or input that demonstrates the failure, paired with the resulting error. Don't describe an input in prose ("a vector of nulls passed to X") when you can show one (makeFlatVector<int64_t>({1, null, 2})); the example carries the meaning without the reader holding context across sentences.
-
Break any long code, query, or error string out into a fenced block on its own line. "Long" means more than ~6 words or anything that wraps the surrounding paragraph awkwardly. This applies whether the long string is paired with another or stands alone — a single long error string embedded mid-sentence still overloads the reader. Patterns:
Lead with the error, then explain:
The query failed with:
Function not registered: my_func(BIGINT)
This happened because the function was registered only under the Presto namespace.
Query + result:
For example:
SELECT my_func(c0) FROM (VALUES 1, 2) AS t(c0)
fails with `Function not registered` because ...
Short fragments (a single column name, a flag, a 2-3-word error name) stay inline.
-
When in doubt, read the paragraph aloud. If you pause mid-sentence to decode it, split or simplify it.
