{"slug": "code-as-documentation-an-sql-development-paradigm-for-the-ai-era", "title": "Code-as-Documentation: An SQL Development Paradigm for the AI Era", "summary": "A developer argues that SQL's declarative nature makes it inherently resistant to the 'code-as-documentation' ideal, as business logic is encoded in syntactic structure rather than expressed explicitly. The developer demonstrates how a production SQL query using window functions becomes nearly impossible to modify when requirements change, and contends that AI-assisted coding fails to solve the core problem of documentation and code falling out of sync.", "body_md": "Let’s first look at the following SQL used in a production environment. The query aims to “merge all overlapping time intervals within each account”:\n\n```\nSELECT account_id, MIN(start_date) AS start_date, MAX(end_date) AS end_date\nFROM (\n  SELECT account_id, start_date, end_date, prev_max,\n    SUM(CASE WHEN start_date > prev_max OR prev_max IS NULL THEN 1 ELSE 0 END) \n      OVER (PARTITION BY account_id ORDER BY start_date) AS gid\n  FROM (\n    SELECT account_id, start_date, end_date,\n      MAX(end_date) OVER (\n        PARTITION BY account_id \n        ORDER BY CASE WHEN account_id IS NOT NULL THEN 1 END, start_date\n        ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING\n      ) AS prev_max\n    FROM acc\n  ) t1\n) t2\nGROUP BY account_id, gid\n```\n\nThis SQL snippet uses window functions MAX()OVER and SUM() OVER for their cumulative-sum technique, along with ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING – syntax most developers would probably need to look up in the documentation. The syntax is completely correct, and the query runs and produces the expected output.\n\nSix months later, the requirement changes – the merging condition shifts from “overlapping alone” to “intervals of no more than 3 days”. Modifying the code to fit this new rule is extremely difficult, basically amounting to a rewrite. You’d need to work out the logic from scratch, mentally re-running the window functions’ computations, just to figure out what to change and how. The code runs, but the cost of understanding it is about the same as rewriting it from scratch.\n\nThis is the reality of SQL development: code is written for machines to execute, not for humans to read.\n\nSQL is a declarative language: it tells the database what to do, not how to do. This creates a problem –** business logic is encoded into the syntactic structure instead of being expressed explicitly.\n\n**\n\nA window function like LAG(amount, 1) OVER (PARTITION BY customer_id ORDER BY month) may correspond to the business concept of “calculating last month’s transaction amount”.\n\nA cumulative-sum snippet like SUM(CASE WHEN ... THEN 1 ELSE 0 END) OVER (...) may correspond to the logic of “conditional segmentation”.\n\nBut these business semantics are implicit in SQL – readers need to infer for themselves what each snippet is actually doing.\n\nEven worse, comments cannot solve this problem. Code changes, but comments don’t always follow. Over time, comments become less reliable than the code itself. And SQL’s nested structure is inherently resistant to comments. Wedged between multiple layers of parentheses, they only make readability worse.\n\n**AI-assisted coding doesn’t solve this problem either.** You generate a SQL snippet with AI, execute and commit it – but you don’t put the prompts in the repository. All that’s left is the final SQL. When the requirement changes, you are back to the same SQL, and have to re-decode its logic from scratch. Even if the original spec written for AI is kept, there’s no guarantee the regeneration produces the same SQL – LLMs aren’t deterministic. Update the spec and regenerate, and you might get a completely different query, which means a re-audit is involved. That’s not a modification, that amounts to a rewrite.\n\nTherefore, AI-assisted coding doesn’t solve the root problem: documentation and code falling out of sync.\n\nUnless, spec and SQL are fused into one – permanently paired, so a spec change automatically updates the SQL.\n\n**“Code as documentation” is an ideal. SQL makes it further out of reach.**\n\nOne misconception needs clearing up here: “code as documentation” doesn’t mean “writing lots of comments in the code”. Comments are a supplement. True “code as documentation” means three things:\n\nThe code structure itself expresses the logic. Reading the code is as clear as reading documentation – no extra explanation needed.\n\nCode and documentation are the same thing. There’s no such problem as “the code changed but the documentation didn’t”.\n\nWhen new hires take over, reading the code is enough to understand the business logic – no extra training and verbal handoffs from the last person needed.\n\nIn the SQL world, this means SQL itself needs to be self-descriptive. Every line of code should tell the reader clearly “what this step is doing”, not “what this syntax does”. But native SQL can’t do this. Multi-layer nesting is everywhere, and readability suffers badly.\n\n**So, the solution is this: make the spec both readable and executable. Spec is documentation; spec is code.**\n\nHere’s what SQLazy does: skip writing SQL directly. Instead, describe the logic as a workflow of steps. Each step is an atomic action. The steps combined are the complete business logic.\n\nTake the example of “merging overlapping intervals” again. Here’s how SQLazy’s workflow expresses it:\n\nThese lines of workflow read almost like natural language: sort, calculate the maximum end date so far, segment rows by condition, aggregate to get the earliest and latest dates. You can guess what most actions mean without ever having to learn them. Only “segment” needs a bit of explanation – it means “group the data by condition”. But paired with the visual step-by-step execution, one glance at the intermediate result makes it click instantly.\n\nRun this example online: [https://www.sqlazy.com/?4Bs](https://www.sqlazy.com/?4Bs)\n\nThis compilable workflow is itself the documentation:\n\nEvery step has clear business meaning: “sort” sorts, “compute” calculates helper values, “segment” groups the data by condition, and “summarize” aggregates.\n\nThe order of steps is the order of thinking. First sort, then compute, then segment, then aggregate – exactly how you’d work through this problem manually.\n\nNo extra comments are needed to explain “what this SQL is doing”. Every line of the workflow already says it clearly.\n\nSix months later, when the requirement changes, just open the workflow and edit the corresponding step directly.\n\nCode and documentation are one thing, not two. This is “code-as-documentation” actually made real.\n\nHere’s another example: group by account, and reset the sequence number whenever the interval between activities exceeds one hour. Here’s how SQLazy’s workflow expresses it:\n\nThree lines of workflow, business logic clear at a glance: “reset the sequence number whenever the interval exceeds one hour”. The equivalent hand-written SQL needs at least two layers of nested window functions, plus LAG-based time-gap calculations. With the workflow, you don’t need to take care of how the SQL is written – the compiler handles that for you.\n\nUnder the traditional model, documentation and code are separate, kept in sync only by hand – and manual sync is error-prone. Documentation gets written, then the code changes without the docs catching up; or the code changes but the documentation isn’t updated.\n\nSQLazy’s model is this: workflow (documentation) → compiler → SQL (code).\n\nCompile the workflow above into SQL (switchable across different databases):\n\nDocumentation is the source. Code is the compiled output. As long as the workflow stays the same, the generated SQL stays the same; when the workflow changes, the SQL regenerates automatically. There’s no more “documentation changed but code didn’t” or “code changed but documentation didn’t” – because they’re two sides of the same thing.\n\nWhen you switch databases, just change the target option – from MySQL to Oracle or from PostgreSQL to Snowflake – and the compiler automatically generates SQL in the matching dialect. No need to modify the workflow. No need to rewrite the documentation.\n\nIn the SQL world, “Code-as-documentation” has always been a hard-to-reach ideal. Without a workflow mechanism like SQLazy’s, code and documentation stay two separate things. You write the SQL, then have to write separate documentation explaining what it does. Syncing the two falls entirely on manual work – and manual work means errors.\n\nSQLazy changes that. It breaks complex SQL into clear steps, which themselves are the documentation, and the compiler guarantees code and documentation stay in sync, permanently.\n\nThis isn’t wrapping a shell around SQL. It’s changing the development paradigm from “writing code for machines to read” to “writing logic for humans to read and letting the machine translate it”. The workflow is for humans. The SQL is for the database to run. The compiler keeps the two in sync – no manual work required.\n\nNext time you open a SQL file written three months ago and can’t make sense of it, ask yourself: if you’d written it as a workflow instead, would you still be in this much pain?", "url": "https://wpnews.pro/news/code-as-documentation-an-sql-development-paradigm-for-the-ai-era", "canonical_source": "https://dev.to/esproc_spl/code-as-documentation-an-sql-development-paradigm-for-the-ai-era-ff1", "published_at": "2026-07-29 06:11:47+00:00", "updated_at": "2026-07-29 06:33:22.740861+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/code-as-documentation-an-sql-development-paradigm-for-the-ai-era", "markdown": "https://wpnews.pro/news/code-as-documentation-an-sql-development-paradigm-for-the-ai-era.md", "text": "https://wpnews.pro/news/code-as-documentation-an-sql-development-paradigm-for-the-ai-era.txt", "jsonld": "https://wpnews.pro/news/code-as-documentation-an-sql-development-paradigm-for-the-ai-era.jsonld"}}