The New Reason for Good Old-Fashioned Best Practices

Photo by Museums Victoria on Unsplash

AI-assisted coding is changing the way software is written. Some developers are getting huge productivity gains, while others find the tools underwhelming or even counterproductive. The same AI models — whether GitHub Copilot, ChatGPT, or newer agentic AI assistants — seem to work like magic for some but fail to deliver much value for others.

Why this strong difference?

The common assumption is that it comes down to prompting skill or experience with AI tools. Those factors certainly play a role, but I think there’s a more fundamental reason: the structure and clarity of the code itself.

A well-organized codebase makes AI dramatically more useful. If your code is modular, well-documented, and follows clear conventions, AI can provide relevant, high-quality suggestions. If your code is messy, inconsistent, or bespoke, AI is just as lost as a junior developer trying to navigate an unfamiliar codebase.

In other words: AI is a multiplier of your existing engineering practices. Good software development habits don’t disappear in an AI-assisted world — they become even more valuable.

1. Encapsulation & Modularity: AI Works Best with Structured Code

One of the best ways to improve AI-assisted development is to write code in small, well-defined pieces.

• Encapsulation keeps implementation details hidden, allowing AI to generate better-scoped suggestions.
• Short, single-responsibility functions make it easier for AI to predict what needs to happen next.
• Functional programming principles (pure functions, immutability, clear inputs/outputs) reduce AI’s margin of error.

A simple test:
Would you rather ask an AI assistant to refactor a 200-line function that does five different things or a 10-line function with one clear purpose?

AI performs exponentially better in the latter case.

The more structured your code, the more AI can help — whether that’s refactoring, debugging, or generating entirely new logic.

2. Clear Naming & Documentation: AI understands English

AI is trained on patterns. If your variables, functions, and comments are clear and descriptive, AI is far more likely to generate correct and useful suggestions.

• Descriptive variable and function names help AI infer meaning.
• Inline comments and docstrings provide context that AI tools can use.
• Consistent naming patterns create a more predictable environment for AI.

Bad Example:

def do_it(a, b):
    c = a + b
    return c

Better Example:

def calculate_total_price(base_price, tax_amount):
    return base_price + tax_amount

In the first case, even a human would struggle to understand what’s going on. AI is no different.

By making your code self-explanatory, you’re not just helping yourself and your team — you’re also making AI a better pair programmer.

3. Strong Conventions: The AI Advantage of Standardization

Some software ecosystems naturally get more value from AI than others — not because the AI is different, but because the codebases are more predictable.

Consider Ruby on Rails, which popularized Convention over Configuration:

• A well-defined project structure means AI can reliably infer where models, controllers, and views belong.
• RESTful API conventions allow AI to predict route structures and HTTP methods.
• Popular formatting & linting rules ensure that AI-generated code blends seamlessly with existing code.

Now compare that to a completely custom, bespoke framework, where every naming convention and file structure is unique. AI struggles because there’s no clear pattern to follow.

Beyond just the choice of language or framework, teams that enforce strong consistency in their codebase — through automated linting, formatting, and other consistency tools — will see even greater benefits from AI assistance.

AI thrives in structured environments. If your code follows well-known conventions, AI becomes a force multiplier — suggesting code that aligns with best practices rather than introducing inconsistencies.

4. Tests Make Everything Better: AI Can Use Tests to Understand and Ensure Correctness

If code is modular and well-structured, AI can better understand it and contribute more effectively to your codebase. A good test suite naturally reinforces this structure — helping developers break code into smaller, more testable, and understandable chunks.

AI-powered development tools are already leveraging this advantage. New IDEs like Windsurf and Cursor can use full-project context, meaning they don’t just generate code in isolation; they can analyze everything in the project. For example, while working on code in the src/ directory, AI can reference related test cases in the tests/ directory to infer intent, verify correctness, and produce better suggestions.

Even more powerful is the rise of agentic AI coding tools — AI systems that don’t just generate code, but also execute and validate it. These tools can:
✅ Write code
✅ Run the test suite automatically
✅ Identify failing tests
✅ Fix issues before human review

This shift is significant: Instead of developers running tests and debugging AI-generated code manually, AI will handle the full loop of writing, testing, and fixing — allowing developers to focus on higher-level decisions rather than micromanaging AI outputs.

Conclusion: AI Doesn’t Replace Best Practices — It Rewards Them

The rise of AI-assisted development doesn’t mean engineering fundamentals no longer matter. Quite the opposite: those fundamentals are the difference between AI being useful or useless.

If your code is structured, modular, clear, and well-tested, AI can help you move faster and smarter. If your code is a monolithic mess, AI will struggle just as much as a human developer would.

So as AI-powered coding becomes more common, it’s worth asking:

Are we making our code easier for AI to work with?

Because whether it’s AI or another developer reading your code, the same principles apply:

• Keep things modular.
• Write clear names and comments.
• Follow established conventions.
• Maintain good tests.

That’s not a new paradigm — it’s just a new reason to follow old but proven best practices.