Readable Code and Fast Queries Are Solved the Same Way: Remove the Reader's Work

May 07, 2026

10 min read

4 views

87%

The hidden cost nobody talks about

What if the biggest performance problem in your codebase is not the machine, but the reader?

That question sounds almost unfair at first. We usually treat documentation and query tuning as two separate disciplines: one belongs to developers explaining intent, the other belongs to databases executing instructions. But both are really about the same thing: reducing the amount of interpretation required to get from surface form to useful result.

A good docstring and a fast SQL query have the same personality. They are direct. They expose intent early. They do not force the reader, whether human or optimizer, to guess what you meant. And when they fail, they fail for the same reason: they make a simple thing harder than it needs to be.

That is the deeper connection. Great software writing, and great database querying, are both acts of making meaning obvious enough that the system can do its job without detective work.

Why humans and optimizers both hate ambiguity

A docstring that begins with a clean one line summary does something powerful: it tells the reader the point before it tells them the details. If the description needs more room, it expands after a blank line. That structure is not decoration. It is a deliberate ordering of information so the reader can stop early if they already understand, or continue if they need more.

SQL optimization works the same way. The database engine does not want to admire your cleverness. It wants a query it can reason about efficiently. If you wrap an indexed column in arithmetic, functions, or negation, you often force the engine to work harder than necessary. If you use a leading wildcard, it loses the ability to narrow the search efficiently. If you sort or group before filtering, you ask the system to process more data than needed.

In both cases, the problem is not complexity itself. The problem is unnecessary complexity before the point of decision.

Think of it like directions to a house. A bad set of directions says, "Drive around the neighborhood, make a few guesses, and then see if one looks familiar." A good set says, "Turn right at the pharmacy, then the third house on the left." Docstrings and SARGable queries are both versions of the second kind. They front load the useful constraint.

The best explanation, like the best query, does not make you do work to recover what could have been stated clearly up front.

This is why the simplest conventions matter so much. Triple double quotes are not a philosophical statement, but they are a signal of consistency. A one line docstring should fit on one line if it is truly obvious. A longer docstring should begin with a summary line, then a blank line, then the elaboration. That shape lets both humans and tools extract the main idea quickly. Query design follows the same logic: filter early, keep the result set small, avoid unnecessary calculations, and only ask for extra work when it is actually needed.

The common principle is not just "be clear." It is preserve the structure that lets meaning be recovered with minimal effort.

SARGability as a philosophy of readability

SARGable is one of those terms that sounds technical until you realize it names a universal design principle. It stands for searched argument able, but the real insight is simpler: can the system inspect your request and use the structure of the data to answer it efficiently?

That is almost identical to what good documentation asks of a reader. Can they inspect the first line and know where the rest is headed? Can they decide, quickly, whether they need to keep reading? Can they use the structure of the text to navigate it?

A non SARGable SQL condition is like a docstring that buries the purpose under prose. Suppose you write a docstring that starts with three paragraphs of context before saying what the function actually does. The information may all be true, but you have hidden the answer behind unnecessary processing. The reader has to scan, infer, and possibly re read before they know the function's purpose.

Now compare that with a query like this in spirit:

Bad: wrap the indexed column in a function, then compare it.
Better: compare the column directly, using a condition that matches the index's structure.

The difference is not merely syntactic. It is conceptual. In the bad version, you ask the system to transform every candidate value before it can evaluate the condition. In the better version, you present the condition in a form the system can recognize immediately.

The same thing happens in writing.

Imagine a Python function docstring for calculate_tax. A weak version might say:

This function processes a number of inputs, applies business rules, and returns a transformed result.

That is technically descriptive, but it makes the reader do the real work of understanding. A strong version says:

Return the total tax owed for a given income and jurisdiction.

Applies progressive brackets and local surcharges.

The first sentence is a summary line. The second sentence adds the relevant nuance. The reader does not have to excavate the meaning. The structure gives it to them in the order they need.

This is the overlooked power of constraints. Constraints are not the enemy of expressiveness. They are what make expressiveness usable. A query that is easier for the database to optimize is often easier for a human to reason about too. A docstring that is easy for a human to read is often easier for tools to extract, index, and present.

That is why these seemingly unrelated rules, like using triple double quotes or avoiding leading wildcards, feel more important the larger a codebase becomes. At scale, every extra guess compounds.

The real enemy is forcing interpretation too early

There is a deeper pattern here: performance falls when interpretation happens in the wrong place, at the wrong time.

A database should interpret as little as possible before narrowing the search. A reader should interpret as little as possible before understanding the purpose. When you violate that rule, you create latency. In SQL, latency is measured in scans, sorts, and unnecessary computations. In writing, latency is measured in confusion, rereading, and context switching.

This is why "filter early" is not just a query tip. It is a mental model for communication.

If you know the essential shape of an idea, state it first. Do not make the reader hold the entire paragraph in working memory just to discover whether the function returns a boolean or a list. Likewise, do not make the database compute on rows you will later discard if you can express the filter upfront.

Here is a useful analogy:

Early filtering is like saying, "Only these are relevant."
Late filtering is like saying, "Let me show you everything, and then I will tell you what mattered."

The second approach feels generous, but it is wasteful. It forces the system to process noise before relevance. In documentation, that means front loading context with no summary. In SQL, that means building a large intermediate result when a smaller one would do.

Sorting and grouping show the same problem. They are often necessary, but if you sort before narrowing the dataset, you are polishing the wrong amount of material. A good docstring has a summary line first because the summary is the equivalent of filtering the question space. It tells the reader which mental bucket to put the thing in. Only then do the supporting details matter.

Clarity is not the absence of complexity. It is the discipline of putting complexity in the right order.

This reframes an important habit: many people think readability is about pleasant prose, and query tuning is about technical micro optimizations. In fact, both are about ordering operations so that the expensive parts happen after the cheap, discriminating parts.

That is why the best explanation often sounds almost sparse. It is not hiding information. It is staging it.

A practical model: the three gates of meaning

If you want a single framework that unifies documentation and query design, use the three gates of meaning.

1. The identification gate

First, make the thing identifiable.

For docstrings, this is the summary line. It should answer, in plain language, what the function, module, or attribute is for. For SQL, this is the predicate that makes the query recognizable to the optimizer, often by allowing the use of an index.

Ask: can a reader or engine tell what this is immediately?

2. The narrowing gate

Second, reduce the search space as early as possible.

For docstrings, this means not burying the key point in paragraphs of context. For SQL, this means filtering with WHERE before sorting, grouping, or expanding the result set. It also means avoiding transformations that prevent index usage when a direct comparison would work.

Ask: have I eliminated irrelevant work before it starts?

3. The expansion gate

Third, provide detail only after the core meaning is secured.

For docstrings, this is the blank line and the longer explanation. For SQL, this is any extra calculation, ordering, or projection that is actually needed after the dataset has been narrowed.

Ask: am I adding depth, or just adding load?

This model is useful because it works at multiple scales. It applies to a single function comment, to a query, to an API response, and even to a product spec. If the first sentence does not help the reader or system identify the shape of the problem, the rest will be harder than it should be.

Consider an e commerce search page. If a customer searches for red shoes, the system should not first fetch every shoe, then derive color, then filter. It should narrow at the earliest possible point. Likewise, a function docstring for find_red_shoes should not begin with a taxonomy lecture on footwear. It should say what it finds, under what constraints, and then add specifics.

The deeper lesson is that good systems are parsimonious with attention.

Key Takeaways

Start with the answer. Whether it is a docstring or a query, put the identifying information first so the reader or optimizer can orient immediately.
Avoid hidden work. Do not wrap indexed columns in unnecessary functions, arithmetic, or negation if it prevents efficient lookup. Do not bury the purpose of a function under excess prose.
Filter before you decorate. Narrow the problem before sorting, grouping, elaborating, or adding context.
Use structure as a signal. A summary line followed by a blank line and detail is not just formatting. It is a map for comprehension.
Optimize for recoverability. Good writing and good SQL both make the intended meaning recoverable with the least possible effort.

The deeper standard: respect the reader's machinery

The most interesting thing about these two domains is that both punish vanity. In documentation, a clever but opaque explanation is worse than a plain one. In SQL, a clever but non SARGable query is often worse than a plain one. In both cases, the system does not reward style points. It rewards work that can be recognized, indexed, and acted on.

That suggests a more general standard for all technical communication: write and query as if interpretation were expensive, because it is.

Humans have limited attention. Databases have limited opportunities to exploit structure. Every extra transformation, every unnecessary wildcard, every vague opening sentence increases the cost of understanding. The highest form of craft is not adding more intelligence to the surface. It is removing the barriers that prevent intelligence from being applied efficiently.

So the next time you write a docstring or compose a query, ask a question that cuts through both worlds:

What can I state now, in the simplest possible form, so that nothing downstream has to guess?

That question is the bridge between elegant prose and fast data access. And once you see it, you realize they were never separate skills at all. They were both disciplines in the same art: making meaning obvious before effort begins.