Skip to main content

Code Review & Business Intent: Making Code Speak "Human"

If AI is the producer of code in the future, the core role of human developers will inevitably shift to Code Reviewers.

A reviewer's worst nightmare is facing hundreds of lines of string-concatenated SQL queries or messy, nested-loop update logic. Under traditional ORMs, you only see the "implementation details" but struggle to decipher the actual "business intent".

TeaQL returns code from "machine-oriented" to "human-oriented" by providing declarative operational abstractions.

1. Eliminating Glue Code: Aggregation Root Graph Save​

Consider a common e-commerce scenario: "A customer cancels an order; we need to update the order status and record an activity log."

Under traditional ActiveRecord or raw SQL patterns, the code might look like this:

// Traditional Review Overhead: Focus is entirely on database transactions and execution order
let mut tx = pool.begin().await?;
let mut order = Order::find(id).fetch_one(&mut tx).await?;
order.status = "CANCELLED";
order.update().execute(&mut tx).await?;

let log = OrderLog { order_id: id, action: "CANCEL", ... };
sqlx::query!("INSERT INTO order_logs ...", log.order_id, log.action)
    .execute(&mut tx).await?;

tx.commit().await?;

Reviewers must spend mental effort checking whether transactions are opened, if foreign keys are correct, and whether the update statement missed any fields.

Under a generated TeaQL model, the same review shape can look like the following. This is pseudocode: with_id_eq, execute_for_single, status, and child-list methods must be read from the generated Order API.

# Model-specific TeaQL pseudocode
let mut order = Q::orders()
    .with_id_eq(id)
    .comment("Query the order selected for cancellation")
    .purpose("Cancel the selected order")
    .execute_for_single(&ctx).await?;

order.set_status("CANCELLED");
order.logs_mut().push(OrderLog::new_cancel_action());

// One audited graph-persistence boundary; verify provider transaction semantics.
order.audit_as("Cancel customer order and add activity log").save(&ctx).await?;

This makes the intended graph change easier to review. The generated model and provider still determine cascade coverage, dirty-field behavior, foreign-key handling, and transaction atomicity; verify rollback on child failure before treating the operation as atomic.

2. Making Intent Visible​

Sometimes query logic is highly complex, involving multiple filter conditions. Reviewers looking at long chain calls often wonder: which PRD requirement is this code satisfying?

TeaQL allows application code to attach an operation comment and business purpose before execution. These values are visible in source and can be exposed through configured runtime observability. Whether they reach a database slow query log depends on the provider, driver, proxy, database configuration, and monitoring pipeline.

The next query is also model-specific pseudocode. It demonstrates the intent terminal order, not generated Task method names:

let tasks = Q::tasks()
    .with_priority_gt(5)
    .with_deadline_lt(Utc::now())
    .with_status_in(vec!["PLANNED", "DOING"])
    // The comment and purpose are visible to reviewers before execution.
    .comment("Dashboard: Get high-priority and overdue focus tasks")
    .purpose("Render the operations focus dashboard")
    .execute_for_list(&ctx).await?;

For reviewers, the pair makes declared intent visible. It remains a declaration, not proof of authorization or requirement correctness. See SRE & Observability for the provider-specific verification boundary.

3. Anti-Corruption: Offloading Complex Validations to the Core​

In complex business systems, hard rules such as "draft tasks cannot have their deadlines modified" are common. Traditionally, these checks are scattered at the beginning of various service methods, making it difficult for reviewers to ensure no check is missed.

TeaQL models/runtimes can expose checker extension points. The exact trait, hook, error, and entity accessors are version- and model-specific; the following is design pseudocode rather than a copy-ready Rust implementation:

#[async_trait]
impl TypedChecker<Task> for TaskStatusChecker {
    async fn on_before_save(&self, ctx: &UserContext, current: &Task, original: &Task) -> Result<(), CheckerError> {
        if original.status == "DRAFT" && current.deadline != original.deadline {
            return Err(CheckerError::Business("Draft tasks cannot have deadline modifications".into()));
        }
        Ok(())
    }
}

A registered and tested checker can centralize a rule, but reviewers must still confirm registration, hook coverage, bypass paths, provider behavior, and negative tests.

Summary​

In the AI coding era, code will be read far more often than it is written. The API design philosophy of TeaQL is built to optimize the human review experience: replacing procedural updates with declarative mutations, and using intent propagation instead of complex documentation, protecting the purity of core business logic.