This is also why long procedural methods make coding life harder for agents. It’s not necessarily length per se, but rather that the longer the method, the more likely that it mixes multiple actions and responsibilities into one weakly described unit. That will confuse any agent.

However, detecting and recognizing a problem is only the start. The harder part is to act on it, and reshape the design in an agent-friendly way. As is often the case with software design, there’s an infinite number of potential paths. The proper choice depends on the problem at hand.

So far, we have looked at simplifying selection logic and transforming long IF-chains into rule pipelines. Now we’re going to expand our refactoring arsenal by taking on the problem of code that squeezes multiple side effects and business rules into the same long function.

Here’s our starting point: (Take a deep breath — it’s a long one)

public void handleCase(
  BackofficeCase backofficeCase, 
  SideEffectPort sideEffectPort) {
    String normalizedTaskType = backofficeCase.caseType().trim().toLowerCase();

    if (normalizedTaskType.equals("refund")) {
        sideEffectPort.appendAudit("case:refund:" + backofficeCase.accountId());

        if (backofficeCase.amountCents() <= 0) {
            sideEffectPort.appendAudit("refund:ignored_non_positive_amount");
            return;
        }

        if (backofficeCase.vip() && backofficeCase.amountCents() <= 20_000) {
            sideEffectPort.issueRefund(
                 backofficeCase.accountId(),
                 backofficeCase.amountCents());
            sideEffectPort.sendEmail(
                 backofficeCase.email(), 
                 "refund-approved-fast-track");
            sideEffectPort.appendAudit("refund:vip_fast_track");
        } else if (backofficeCase.hasOpenDispute()) {
            sideEffectPort.sendEmail(
                backofficeCase.email(), 
                "refund-needs-manual-review");
            sideEffectPort.appendAudit(
                "refund:manual_review_dispute");
        } else {
            sideEffectPort.issueRefund(
                backofficeCase.accountId(), 
                backofficeCase.amountCents());
            sideEffectPort.sendEmail(
                backofficeCase.email(), 
                "refund-approved-standard");
            sideEffectPort.appendAudit("refund:standard");
        }
        return;
    }

    if (normalizedTaskType.equals("welcome")) {
        // ...lots of code for the welcome flow...
        return;
    }

    if (normalizedTaskType.equals("ban")) {
        // ...lots of code for the ban flow...
        return;
    }

    if (normalizedTaskType.equals("export")) {
        // ...lots of code for the export flow...
        return;
    }

    sideEffectPort.appendAudit(
       "case:unknown:" + backofficeCase.caseType());
}

That’s a lot. The preceding code seems to handle different kinds of backoffice work. We see that a refund case issues money back and sends an approval email, whereas the welcome case would send onboarding material, and so on. The method is non-trivial.

Part of the challenge is that the outcomes of the distinct steps aren’t uniform values. Rather, they represent workflows and tasks that need to be performed.

Subscribe now

This is where the design pattern Command becomes useful. Instead of letting the method contain every possible choice, we encapsulate each business rule as a distinct executable unit.

The first step is to move the logic for each task into domain-named command objects:

private static final BackOfficeTask PROCESS_REFUND = new ProcessRefund();
private static final BackOfficeTask SEND_WELCOME_PACKAGE = new SendWelcomePackage();
private static final BackOfficeTask EVALUATE_ACCOUNT_BAN = new EvaluateAccountBan();
private static final BackOfficeTask EXPORT_ACCOUNT_DATA = new ExportAccountData();
private static final BackOfficeTask HANDLE_UNKNOWN = new HandleUnknown();

private static final List<BackOfficeTask> DOMAIN_COMMANDS = List.of(
        PROCESS_REFUND,
        SEND_WELCOME_PACKAGE,
        EVALUATE_ACCOUNT_BAN,
        EXPORT_ACCOUNT_DATA
);

public void handleCase(BackofficeCase backofficeCase, 
                       SideEffectPort sideEffectPort) {
    String normalizedTaskType = backofficeCase.caseType().trim().toLowerCase();
    commandFor(normalizedTaskType).execute(backofficeCase, sideEffectPort);
}

We’ll go over the details and mechanism soon, but note how the offending handleCase method went from potentially hundreds of lines to just two lines of code. What happened?

Well, we introduced a small command model around the existing logic:

• BackOfficeTask is a shared abstraction for executable pieces of backoffice work. A pure interface.

• ProcessRefund, SendWelcomePackage, EvaluateAccountBan, and ExportAccountData are concrete tasks, each owning one business rule family.

Their implementation is straightforward:

private interface BackOfficeTask {
    // purpose: selection -- is this the task to execute for the given input?
    boolean supports(String normalizedTaskType);

    // purpose: behavior -- encapsulates the logic and actions for a specific task.
    void execute(BackofficeCase backofficeCase, SideEffectPort sideEffectPort);
}

private static final class ProcessRefund implements BackOfficeTask {
    @Override
    public boolean supports(String normalizedTaskType) {
        return normalizedTaskType.equals("refund");
    }

    @Override
    public void execute(BackofficeCase backofficeCase, 
                        SideEffectPort sideEffectPort) {
        sideEffectPort.appendAudit(
            "case:refund:" + backofficeCase.accountId());
        // existing refund logic preserved here
    }
}

Like any design pattern, there aren’t any fixed rules or structure for what the implementation shall look like. Rather, we need to adapt the pattern to our context.

In this case, we do a simple linear search of the supporting command to match a given input task:

private static final List<BackOfficeTask> DOMAIN_COMMANDS = List.of(
        PROCESS_REFUND,
        SEND_WELCOME_PACKAGE,
        EVALUATE_ACCOUNT_BAN,
        EXPORT_ACCOUNT_DATA
);

private static BackOfficeTask commandFor(String normalizedTaskType) {
        for (BackOfficeTask command : DOMAIN_COMMANDS) {
            if (command.supports(normalizedTaskType)) {
                return command;
            }
        }
        return HANDLE_UNKNOWN;
    }

DOMAIN_COMMANDS is a list of known tasks, and commandFor(...) is the selector that finds the matching task for the current case type. This structure is a form of responsibility chain where each command decides if it applies. (It’s also an example on combining multiple patterns in one solution).

The HANDLE_UNKNOWN command acts as a safe default. It represents a variation of the Null Object pattern, ensuring that the system always has a valid command to execute, even when no specific case matches.

he original handleCase(...) method is now an orchestrator, delegating the actual work to the selected task instead of containing every branch itself:

public void handleCase(BackofficeCase backofficeCase, 
                       SideEffectPort sideEffectPort) {
    String normalizedTaskType = backofficeCase.caseType()
                                               .trim()
                                               .toLowerCase();
    commandFor(normalizedTaskType).execute(
       backofficeCase, sideEffectPort);
}

That is the first benefit. Whereas the original method was organized around branching, our refactored version is organized around domain tasks.

Note A natural next refactoring would be to remove the string-based selection entirely. We’ll do just that at the end of the article. For now, let’s bear this pain together.

Why this helps human review

The long-method version forces the reader to keep several different concerns active at once.

While reading handleCase, you are not just tracking which branch applies. You are also tracking what kind of business action each branch performs and which side effects belong together. That is a bad fit for human working memory. Further, code that lacks cohesion also increases the risk for unexpected feature interactions: one branch changes a shared state, triggering downstream failures.

Distinct commands reduce that cognitive load by turning the large procedural mess into named chunks. The resulting command objects become cognitive units for reasoning. The reviewer can understand the dispatcher as one concern and each business rule as another. Future extensions are now likely to be additions rather than complex edits of a large block of code.

Why this matters in AI-first development

In the original method, the model has to infer that a cluster of statements represents a refund decision, a welcome flow, etc. The refactored code stops making the model reverse-engineer intent from branch shape by giving the code an explicit semantic structure. Those building blocks are now explicit domain actions.

The structure reduces ambiguity and guides both planning and modification. If an agent needs to change export behavior, ExportAccountData is the obvious unit to inspect. If it needs to reason about refund policy, ProcessRefund is the unit. The edit surface becomes narrower, and the risk of collateral changes drops.

Bringing the solution structure closer to the problem domain serves the translation from prompt to desired outcome.

This is the core idea behind refactoring towards AI-friendly code: make meaning explicit before asking the model to work with it.

Design guardrails

Use this refactoring pattern when a method coordinates several distinct actions with different side effects and/or workflows:

• Preserve business logic while moving code into commands.

• Keep the public API unchanged during the initial transformation.

• Name concrete commands by domain purpose, not architectural suffixes.

• Let each task encapsulate its side effects.

From domain actions to stronger API: evolving the design

Often, introducing explicit commands reveals further possibilities to simplify. As an example, take another look at our refactored code:

public void handleCase(BackofficeCase backofficeCase, 
                       SideEffectPort sideEffectPort) {
    String normalizedTaskType = backofficeCase.caseType().trim().toLowerCase();
    commandFor(normalizedTaskType).execute(backofficeCase, sideEffectPort);
}

Right now, the commands are an implementation detail inside that class. That’s usually a good start, allowing us to optimize for local reasoning.

However, I often find the commands themselves might be part of a stronger API. So what if we start to expose these objects directly to the calling client?

// refactoring note: we now accept a Task rather than a stringly typed 'case'
public void handleCase(BackOfficeTask taskToPerform, 
                       SideEffectPort sideEffectPort) {
    taskToPerform.execute(sideEffectPort);
}

In the preceding code we did just that: we shifted the API to accept a generic BackOfficeTask rather than having to create it ourselves. A nice side effect is that we get rid of the nasty task normalization with its complex and accidental string manipulations. (That is, getting rid of backofficeCase.caseType().trim().toLowerCase() — What’s not to like about that?)

The reason this usually works well as the next refactoring step, is because at the call site, context tends to be obvious; we know if we want a refund, send a welcome package, or export data. So why not take advantage of that contextual knowledge in the API responsbile for the corresponding actions?

As an added benefit, that improved API would also align with the Open-Closed Principle, meaning new clients can extend the program with new types of tasks without modifying the code processing them. Coding agents generally perform well in code with clear intent and a consistent structure that naturally communicates its extension points. The more explicit the structure, the less reconstruction work to perform.

They usually start small: one &&, a few ||,then one more clause to patch an edge case. Soon they have grown into little puzzles, but not for our amusement.

Every time someone reads such code, they have to reconstruct the intent from raw logic instead of seeing the business rule directly. What should be obvious becomes something you have to figure out.

Take this condition:

String tail = originalName.substring(i).toLowerCase();
if (tail.startsWith("admin") || tail.startsWith("owner") || tail.startsWith("root")) {
    return true;
}

Looking at that code, we can of course derive its meaning. But only after mentally parsing each clause, hold the alternatives in working memory, and then reconstruct the intent. We probably did not read it and think:

so simple — this checks for reserved role names

That reconstruction friction is exactly what good refactoring should remove. Starting from code like:

Read more

This pattern addresses that problem by turning branching logic into an explicit pipeline of rules. Instead of hiding decisions in control flow, we make them visible, ordered, and easy to change.

The previous pattern handled selection. This one handles workflows.

Consider the following code:

// NOTE: Simplified example to illustrate the core issue.
// Real-world versions are typically much larger and harder to reason about.

// Admin accounts are usually safe, unless someone tries to sneak weird separators into the raw name.
if (context.accountType().equals("admin") && !hasWeirdSeparators) {
    if (looksLikeImpersonation(normalizedName)) {
        logReview(100);
        return new ReviewResult(
                   "manual", 
                   "Admin-like username requires manual review");
    }
    auditRuleHit("ALLOW_SAFE_ADMIN_USERNAMES", context);
    return new ReviewResult("allow", "Admin username looks safe");
}

// 1. Block quoted fragments that may hide suspicious content
if (originalName.matches(".*\"[^\"]*\".*")) {
    logReview(101);
    notifyReviewQueue(context.userId(), "quoted-fragments");
    return new ReviewResult("manual", "Quoted fragments require manual review");
}

// 2. Block bracketed fragments that may hide tags or role names
if (originalName.matches(".*\\[[^\\]]*\\].*")) {
    logReview(102);
    String reason = originalName.contains("[admin]")
            ? "Bracketed role labels require manual review"
            : "Bracketed fragments require manual review";
    return new ReviewResult("manual", reason);
}

// ...think many more lines with conditionals and blocks...

if (normalizedName.contains("test") && normalizedName.length() < 8) {
    logReview(107);
    flagPattern(context.userId(), "short-test-username");
    return new ReviewResult(
               "manual", 
               "Short usernames containing 'test' require review");
}

return new ReviewResult("allow", "No suspicious username patterns detected");

So what’s the problem here?

The logic we are trying to express is a workflow. But the code does not say that. It hides the workflow inside a sequence of decisions, all compressed into a single method.

That style works right up until someone needs to change it. (And what good is code that an AI — or you — cannot safely change?) The consequence is that you cannot touch one rule without re-reading all the others, because the branching structure hides both order and intent.

The refactoring is simple: stop expressing policy as a branching maze and express it as an explicit decision pipeline.

After:

private static final List<ReviewRule> REVIEW_PIPELINE = List.of(
        ALLOW_SAFE_ADMIN_USERNAMES,
        REQUIRE_MANUAL_REVIEW_FOR_QUOTED_FRAGMENTS,
        REQUIRE_MANUAL_REVIEW_FOR_BRACKETED_FRAGMENTS,
        REQUIRE_MANUAL_REVIEW_FOR_REPEATED_PUNCTUATION_BEFORE_DIGITS,
        REQUIRE_MANUAL_REVIEW_FOR_INVISIBLE_CHARACTERS,
        REQUIRE_MANUAL_REVIEW_FOR_RESERVED_ROLE_NAMES,
        REQUIRE_MANUAL_REVIEW_FOR_LEADING_OR_TRAILING_UNDERSCORE,
        REQUIRE_MANUAL_REVIEW_FOR_SHORT_TEST_USERNAMES
);

public ReviewResult reviewUsername(SignupContext context) {
    for (ReviewRule rule : REVIEW_PIPELINE) {
        Optional<ReviewResult> reviewResult = rule.tryReview(context);
        if (reviewResult.isPresent()) {
            return reviewResult.get();
        }
    }
    return allow("No suspicious username patterns detected");
}

What we have done here is adapt the classic Chain of Responsibility pattern to a refactoring problem. The original formulation comes from the Gang of Four book, where a request is passed along a chain of handlers until one of them decides to handle it (Gamma, Helm, Johnson, and Vlissides, Design Patterns: Elements of Reusable Object-Oriented Software, Addison-Wesley, 1994). Here, we use the same core idea, but in a stripped-down and more explicit form: a linear sequence of small rules.

After this transformation, the logic and behaviour are driven by the table. Each rule in that table is simply a named method reference. Think of them as pointing to small rule methods. Here’s an example:

private static final ReviewRule REQUIRE_MANUAL_REVIEW_FOR_QUOTED_FRAGMENTS =
        Reviewer::requireManualReviewForQuotedFragments;

private static Optional<ReviewResult> requireManualReviewForQuotedFragments(SignupContext context) {
    if (context.originalName().matches(".*\"[^\"]*\".*")) {
        logReview(101);
        notifyReviewQueue(context.userId(), "quoted-fragments");
        return Optional.of(manual("Quoted fragments require manual review"));
    }
    return Optional.empty(); // Optional.empty means: this rule does not apply, pass to next rule
}

Each rule becomes a small, named method that does one thing. It either returns a decision or passes control forward.

Also, the rules might not be just predicates. They also own their side effects. Logging, auditing, and notifications now live next to the decision that triggers them.

Note that we kept the original logic and structure (we only changed the return shape to Optional so the workflow can be driven by the pipeline). There is still cleanup we could do in those rule methods, but we do that stepwise: first make structure and intent explicit, then iterate once everything works. Too-large refactoring steps are a reliable way to sidetrack an agent.

Implementation Tip: Go Functional

If you prefer a more functional style, you can also express the orchestration as a pipeline operation:

public ReviewResult reviewUsername(SignupContext context) {
    return REVIEW_PIPELINE.stream()
            .map(rule -> rule.tryReview(context))
            .flatMap(Optional::stream)
            .findFirst()
            .orElseGet(() -> allow("No suspicious username patterns detected"));
}

In C#, this maps naturally to LINQ; in Python, a generator-based first-match approach gives a similar shape.

I chose the explicit loop and if check in this chapter because it doesn’t require any detailed Java knowledge to follow, and because I prefer the pure simplicity of the more procedural form. Sometimes, a simple if is exactly what the doctor orders.

So the pipeline is not magic. It is just an ordered list of named decisions. The original logic is still there, but now encapsulated in stable and readable identities with their execution order controlled by the pipeline.

The Hard Part: Naming Rules

The challenging part in this refactoring is to identify the rules to extract and name. You might be fortunate to have comments explaining what the following code block does.

The original code has some of that: // 1. Block quoted fragments that may hide suspicious content.

But not everything is commented. Look at the final rule guarded by the if (normalizedName.contains("test") && normalizedName.length() < 8) { clause.

In the latter case, we need to go into detective mode and try to figure out the purpose and intent. (And the magic number 8 is not helping us here). Often, an LLM can help with the task -- language models are surprisingly good at naming things, a skill we humans struggle with.

Why this is better

In the conditional-heavy version, order is implicit in the branch clutter. In the refactored pipeline version, order becomes first-class data. You can point to the pipeline and answer immediately: “what runs first, what runs last, what short-circuits?”

That makes change less speculative. Add a new rule? Insert one pipeline entry and one method. Modify an existing rule? Open one dedicated method and stop there.

If that sounds familiar, it should. This is the same gain we saw in Express Selections as Tables. There, we refactored branching logic into a declarative lookup table. Here, we refactor decision logic into a declarative pipeline. In both cases, behaviour stops being buried inside control flow and starts being expressed as explicit structure.

That means extension becomes simpler and safer. They are now declarative changes. That matters to an AI agent too: the code now advertises where behaviour lives, in what order it runs, and how it can be extended without guesswork.

When to use this pattern

Use responsibility chains when:

• one method contains many policy checks,

• checks are mostly independent decisions,

• rule order matters,

• short-circuit behavior is desired.

Do not force this pattern everywhere. If conditions share heavy mutable state, or if you are selecting behavior families, strategy/polymorphism may be a better fit.

Design guardrails

To keep this refactoring honest:

• Preserve API and behavior.

• Keep the same decision order.

• Keep each rule narrow and intention-revealing.

A good litmus test is this:

If you cannot describe what a rule does in one short sentence, the rule is probably doing too much.

Why this matters in AI-first development

Conditional-heavy code consumes tokens without increasing information density.

LLMs have a limited attention budget. Every extra token competes for that budget, and unstructured control flow forces the model to spend it on reconstruction instead of reasoning. Such code burns more tokens than a Meta employee looking to land on the internal leaderboard.

Responsibility chains reverse that tradeoff. They convert implicit flow into explicit decisions. That reduces ambiguity, narrows edit scope, and makes automated transformations safer. All of that improves machine-readability:

• The orchestrator method is tiny, obvious, and stable.

• Rule intent is encoded in method names, not inferred from nested conditions.

• The agent can focus on one decision at a time instead of reconstructing control flow from a dense branch forest.

In other words: this is not just a stylistic opinion. It is about better geometry for change.

Take a switch statement where each branch selects a value and returns it:

switch (creature) {
    case DRAGON:
        return new SnackRecommendation("Charcoal-grilled marshmallows");
    case VAMPIRE:
        return new SnackRecommendation("Tomato juice on ice");
    case WIZARD:
        return new SnackRecommendation("Mystic instant noodles");
    default:
        return new SnackRecommendation("Chef special surprise");
}

When selection logic is encoded as branching, we force the reader to simulate the program to discover a simple fact: there is a direct mapping from input X to value Y.

A switch with a few case labels might not be the worst idea, but I’m confident that we’ve all seen switch-cases stretching over tens and hundreds of lines of code. Each time an agent wants to add a new case, it has to modify that function.

A better solution is to state the relationship between input and result value directly. A table does that:

private static final SnackRecommendation RECOMMENDATION_FOR_MYSTERIOUS_GUEST =
        new SnackRecommendation("Chef special surprise");

private static final Map<Creature, SnackRecommendation> RECOMMENDATIONS_BY_CREATURE = Map.of(
  Creature.DRAGON,  new SnackRecommendation("Charcoal-grilled marshmallows"),
  Creature.VAMPIRE, new SnackRecommendation("Tomato juice on ice"),
  Creature.WIZARD,  new SnackRecommendation("Mystic instant noodles")
);

public SnackRecommendation snackFor(Creature aHungryOne) {
    return RECOMMENDATIONS_BY_CREATURE.getOrDefault(
            aHungryOne,
            RECOMMENDATION_FOR_MYSTERIOUS_GUEST
    );
}

This is not a Java-specific trick. In Python, the same idea is usually expressed with a dictionary. In C#, you’d typically use a Dictionary<TKey, TValue>. The syntax differs, but the pattern is the same: move the mapping out of control flow and into a data structure that states the relationship directly.

Refactoring to a table makes the design intent explicit: there is a fixed set of domain values, and each one maps to a recommendation. Better, any changes to the behavior of the code are now purely declarative. You modify the table, but don’t have to change any logic. That’s about as safe as it gets.

This refactoring has several benefits:

• Separates selection data from selection mechanics.

• Removes repetitive branching noise that adds no new meaning.

• Makes missing cases and defaults easier to reason about.

• Gives both humans and agents a single, canonical place to inspect and modify.

• Reduces the amount of code an AI must read before making a safe change.

There is also a more subtle design gain here: once the selection becomes a table, it becomes easier to ask the right domain questions. Should this really be a fallback? Or should the default be an exception as a missing entry would indicate an internal bug? Those questions are much harder to see when the logic is buried in a switch.

When this refactoring applies

Use a table when branches are doing little more than selecting a value.

Typical signs:

• Each branch returns a constant or near-constant value.

• The logic is keyed by a domain concept such as status, type, code, or state.

• There is little or no branch-specific algorithmic behavior.

In contrast, do not force everything into a table. If each branch contains meaningful behavior, side effects, or a non-trivial algorithm, then you probably have a behavioral variation problem rather than a selection problem. In that case, reach for polymorphism, composition, or dedicated strategy objects. (We’ll cover these patterns too later).

A blunt but useful rule is:

If your switch mostly chooses data, use a table. If it mostly performs behavior, use objects or functions.

Why this matters more in the age of AI

Humans are good at glossing over repetitive code. We see a switch, we skim, and we tell ourselves we got the idea. Often we did. Sometimes we did not.

Agents must process the structure more mechanically and literally. A long conditional construct increases the amount of code they need to ingest before they can infer the domain model. That increases token cost and the chance of error. The code becomes mechanically readable but semantically vague.

A table improves that situation because it is closer to the underlying purpose of the program. Instead of reading branches and reconstructing a mapping, the agent sees the mapping directly. This is one of the recurring themes in AI-readable code: refactor toward explicit structure. Make the code say what it is.

Subscribe now

In many cases, the problem is not complexity itself, but where that complexity lives. We tend to express domain concepts through control flow—if statements, switch blocks, nested conditionals—rather than through explicit structure. That makes the code harder to read, harder to change, and harder for AI to work with.

Design Right-Sized Functions

Many a code reviewer has battled over function length. The argument usually alternates between two polar opposites: should we prefer many small methods, or is it better to keep related code in one large chunk?

Ultimately, that question misses the point. It is the wrong question to ask. Rather, we should focus on right-sizing our functions.

Fundamentally, the cost of working with code is dominated by how long it takes to answer questions like:

• What does this code do?

• What will break if I change it?

• Where should I make the change?

Large functions increase that cost because they force us — and our agents — to scan, interpret, and simulate more logic before we can act. Right-sized functions reduce that burden. Not by being small, but by being understandable.

Introduce Functions Your Brain Loves

Human working memory is limited. We do not read code token by token—we read by chunking.

A good function acts as a cognitive unit. It lets us replace a block of logic with a single idea.

Compare:

if (user.isVip() && order.amount() < 20000 && !order.hasDispute()) {
    // ...
}

with:

if (isEligibleForFastTrackRefund(user, order)) {
    // ...
}

It’s a simple example, yet the second version compresses detail into meaning. It allows the reader to move forward without simulating every condition.

That matters even more in an AI-driven workflow. As humans, we are no longer just authors of code. We are:

• orchestrators and technical leaders, guiding agents toward the right implementation,

• and reviewers, validating and correcting what those agents produce.

Both roles depend on quickly understanding intent. Functions that align with how we think make that possible.

Subscribe now

Introduce Functions Your AI Agent Loves

The same properties that help humans understand code also benefit AI systems—but for different reasons.

AI models do not “understand” code the way humans do. They infer meaning from patterns in tokens and depend heavily on what is explicitly expressed in the code.

Research shows that naming plays a critical role. When meaningful identifiers are replaced with arbitrary names, model performance drops significantly. Current models rely heavily on literal features—names, structure, and local context—rather than inferred semantics.

That has practical implications:

• A well-named function communicates intent directly.

• A poorly named function forces the model to reconstruct meaning.

• Larger, unstructured methods increase the amount of code the model must process before making a safe change.

In other words, good function design reduces both cognitive load and token load.

How long should a function be? Findings from research

So, all this talk about right-sized functions. Couldn’t we just come up with a number? Sure. What about 24? That number comes from a 2022 study which examined the evolution of ∼785K Java methods.

24 lines is lower than all corporate coding standards I’ve ever seen. Those tend to settle for variations of the idea that the whole function should fit on screen or, old school, a page of paper. (See the coding rules from NASA’s Jet Propulsion Lab for a good example).

But even a number backed by data is misleading. Code doesn’t magically become unreadable once you add line 25. Size alone is a poor predictor of complexity.

Empirical research consistently shows that maintainability and understandability cannot be reliably inferred from method length. Such models are not very accurate. Instead, factors like naming, cohesion, nesting depth, and domain complexity are all more important.

With coding agents now working directly on our code, hard limits become even less useful. Agents benefit from explicit structure and clear intent, not from arbitrary line counts.

🎗️ There is no fixed number of lines that makes a function “good”.

A long function is not a problem by itself. A function that mixes multiple concerns, hides intent, or resists naming is.

So the goal of refactoring is not shorter functions per se. It is better structure.

When we extract well-named functions with clear purpose, we introduce meaningful chunks into the design. Those chunks make it easier to reason about the system and often reveal better abstractions.

Refactoring is not about slicing code into smaller pieces. It is about discovering the right boundaries.

Making it worse: split at random

Discovering the right boundaries is not as simple as just extracting pieces of code into functions.

Consider this:

// ⚠️ WARNING: do *not* try this at home
void processOrder(Order order) {
    impl1(order);
    impl2(order);
}

void impl1(Order order) {
    // first half of logic
}

void impl2(Order order) {
    // second half of logic
}

This satisfies a line-count rule. It also keeps your company-mandated linting tool happy. What it doesn’t do is improve understanding.

Splitting functions based on arbitrary thresholds makes the design worse. Code that belongs together should stay together. Split by concept, never by lines.

Beyond Method Extraction: define concepts

Now, there’s one more thing to consider. Making a method shorter is not necessarily about splitting it into smaller ones. (In fact, I suspect that this misconception is a common reason for the keyboard wars around function length).

Consider:

String allowedHumidityBand = request.allowedHumidityBand();
String[] humidityParts = allowedHumidityBand.split(”-”);
int minHumidity = Integer.parseInt(humidityParts[0]);
int maxHumidity = Integer.parseInt(humidityParts[1]);

In the preceding code, there seems to be a domain concept involving humidity limits. But that concept is scattered across Strings and ints. The reader has to infer that all of these values are really one thing: a humidity band.

A simple improvement is to define that concept directly:

HumidityBand humidityLimit = parseHumidityBand(request.allowedHumidityBand());

That is a small change, but it matters. Yes, we went from four lines of code to one, but length is secondary. The important part is that the code now aligns with the problem domain. The parsing details are encapsulated, so they no longer distract from the overall purpose of the method. You, and your agent, can now talk about a HumidityBand instead of passing around parsing artifacts and loose integers. That makes the intent clear.

From Hidden Logic to Explicit Structure

Functions are the first unit of structure in a codebase. They define how logic is grouped, how intent is communicated, and how change is localized. If the function boundaries are wrong, everything built on top of them becomes harder to understand and harder to evolve.

That is why function design matters so much. It is where structure begins.

It’s also where this series continues. In the next posts, we’ll take on specific patterns that turn tangled control flow into explicit structure:

• conditionals → named rules

• branching → tables

• logic blobs → composable pipelines

If you enjoy taking messy code apart and rethinking its design, you’ll like what’s coming next. (And yes, we’ll break a few “best practices” along the way).

My next post is one of the most common problems: selection logic hidden inside conditionals. Subscribe if you want those patterns as they’re published, and see you soon!

Subscribe now

Subscribe now

In the beginning

In the beginning, there was code. Lots of it. And not all of that code was, shall we say, in the best possible shape. Then came the machines, first learning from that code, and then beginning to write it themselves.

Today, AI is transforming the software industry—and yet, we’re only getting started.

Why code still matters

Great code is no longer just readable. It must be machine-legible and transformable.

If AI cannot understand your code, you need to guide the agents with clear, structured, and concrete examples. This publication explores the principles, techniques, and refactoring patterns that shape how we should design software in the AI age.

Today, anyone can create a non-trivial software product. In fact, you can do so without knowing how to code. AI has come a long way.

However, writing the initial version of a product was never the key challenge. (That’s not to say it’s easy—there are enough infamous examples of systems that never shipped.) Most of the cost comes after the initial version is shipped, assuming you have product–market fit and customers.

The more successful your product, the stronger the pressure for new features and improved capabilities. This is where software design and architecture start to matter.

In 2026, my research colleagues and I published a paper on AI-friendly code. In short, we found that to do a good job, an AI agent demands better code quality than a human would.

Let’s repeat that, since it’s so important:

To minimize defects, keep token costs reasonable, and ensure your AI implements the right thing, you need to care about code quality.

But won’t AI become good enough to work on any code?

AI for coding has evolved at a ridiculous speed, and it’s tempting to believe that the future will be even brighter.

So instead of thinking about software design, perhaps we could all just relax and let time (and Big Tech) do its job?

I’ve been hearing that argument since early 2023. And so far, we’re not there.

It’s not an unsolvable problem, but several forces work against it:

• AI reflects its training data. Coding models are trained on real codebases…and most real codebases are not great.

• LLMs lack an objective measure of what “good” looks like.

• Without clear structure and intent, AI becomes directionless. It can — and will —modify code, but it cannot reliably understand it.

That last point matters more than it might seem. When code does not communicate intent, every change becomes speculative, for humans and machines alike.

The software engineering renaissance

Fortunately, AI is still immensely useful even in the worst possible spaghetti code. It just needs direction.

And this is where you, the software professional, comes in.

Programming might be dead, but software design is more relevant than ever.

To perform well, agents need structure. That structure comes in the shape of:

• Consistency: predictable structure, obvious places to look

• Documented principles and constraints

• Reusable know-how (what we might call “skills” today)

• Alignment between problem and solution domains

• No surprises: because surprises are expensive, for both humans and machines

At this point you might wonder: weren’t these concepts important pre-AI? Absolutely. Great software has always been built on this foundation.

The difference in the AI era is speed: mistakes, ignorance, and shortcuts compound at machine speed. We can no longer get away with sub-standard architectures, nor can we compensate for poor design by throwing more people (or agents) at the problem. Clean code is not enough—we need great software design.

What you’ll find here

This publication is about making code easier to understand, safer to change, and more predictable to evolve by both humans and agents.

Much of that work comes down to structure.

A large part of the problem with poor-quality code is a lack of modularity and a failure to communicate intent. When code hides what it does, everything becomes harder:

• It is difficult to find the right place to make a change

• It is risky to modify behavior without breaking something else

• It is expensive for an AI to even locate the relevant logic

This publication takes on that problem. It’s all about code that machines can safely transform.

Subscribe now

Agentic coding is harder, not easier

Sometime in late 2025, I wrote my final lines of code. I wasn’t aware of it at the time, but that day marked a transition after almost four decades of programming. I’ve created and shipped plenty of code since then, but with one key difference: that code wasn’t written by hand. It was written by AI agents that I directed.

Surprisingly, I don’t long for the old days. I find agentic coding more rewarding, and the shift isn’t as large as I would have expected. It still feels like programming, just with larger steps and faster feedback.

That said, I’m grateful for those years of manual coding. Without that experience, I wouldn’t have been able to steer coding agents in the right direction, nor would I have known what and how to correct in the resulting software design (those corrections being agentic too, of course).

Why this publication exists

The short answer is that I simply love to write, and I enjoy developing software. Hopefully that shines through.

So what to I have to share? I’ve spent decades working with software systems across domains, paradigms, and organizations. Over time, certain patterns keep appearing. Some of those patterns transform a solution to make the code easier to work with, while others make the design more fragile.

In the AI era, those patterns matter even more.

In my next posts, I’ll share:

• refactoring patterns that improve structure and intent

• design principles that make code easier to evolve

• and occasional reflections on topics that interest me, for example what the developer role is becoming

Because one thing is clear: The future of software development is not less engineering. It is engineering at a higher level of abstraction.