Codebase Conventions and Standards

Conventions are the invisible load-bearing walls in codebases. When you open a file, you immediately know where to find things. When you see a variable name, you know what it is. When you review code, you're not arguing about indentation—you're evaluating logic. This is what conventions do. They automate the easy decisions so humans can focus on hard ones.

The average developer spends more time reading code than writing it. Good conventions make reading faster. You don't have to hold ten different naming schemes in your head. You don't have to search through a labyrinth of directory structures to find the file you need. You don't wonder whether a function should exist as a method or a utility.

Why This Matters

Consistency reduces cognitive load. This isn't philosophical—it's neuroscience. When code follows predictable patterns, engineers recognize them immediately and allocate mental resources to the problem, not the syntax. A variable named user is immediately clear. A file named payment-processor.ts tells you what it does. A function named calculateTotal() is obvious. The flipside: inconsistent naming forces you to read the code to understand the intent.

Onboarding accelerates dramatically. A new engineer's first week involves learning your problem domain, architecture, and technology choices. They shouldn't also be deciphering your naming schemes. When conventions are strong and documented, they get productive in days instead of weeks.

Teams move faster in code review when style is automatic. If your linter handles formatting, your reviews don't include comments about spaces or semicolons. You're only discussing logic, naming, and architecture. That's where human judgment belongs.

Quality naturally improves. When style is consistent, bugs surface more obviously. Dead code stands out. Copy-paste errors are visible. Unusual patterns jump out because the rest of the code looks different.

What to Standardize

Naming conventions are your first priority. Different teams standardize differently, but consistency matters more than which convention you choose. Some teams use camelCase for variables and PascalCase for types. Others use snake_case everywhere. Pick one and enforce it.

Be specific about what you standardize:

• Boolean variables: isActive, hasPermission, canDelete (prefix with is, has, or can)
• Collections: pluralize them. users not userList or userArray
• Private members: prefix with underscore or use language conventions
• Constants: SCREAMING_SNAKE_CASE
• Event handlers: handleClick, onSubmit, whenDataLoads

The naming convention should reflect what the variable is. Don't name a user ID data just because it comes from a data structure. Name it userId. Don't call a flag x. Name it isArchived.

File and directory organization should mirror your domain structure, not just your layer structure. Create directories by feature or domain first, then layer underneath. Instead of:

src/
  components/
  services/
  utils/
  models/

Consider:

src/
  features/
    users/
      components/
      services/
      models/
    payments/
      components/
      services/
      models/
  shared/
    components/
    utils/

The second structure makes it obvious where to find code related to a feature. When someone needs to understand user management, they go to one directory. The first structure requires jumping between five directories.

Import ordering prevents merge conflicts and makes code scanning easier. A standard order:

1. Standard library imports
2. Third-party imports
3. Local imports
4. Side-effect imports

Within each group, sort alphabetically. A tool like eslint-plugin-import enforces this automatically.

Comment style should be consistent. What types of comments are acceptable? When do you write JSDoc comments? When do you write inline explanations? A reasonable standard:

• JSDoc for public functions and exported types
• Inline comments for non-obvious logic, not obvious logic
• No commented-out code (version control handles history)
• Use them to explain why, not what (the code shows what)

Example of useless comments:

// increment counter
counter++;

Example of useful comments:

// we wait for user confirmation because the operation is irreversible
await confirmDelete();

Error handling patterns should be standardized. How do you create custom errors? How do you structure error messages? How do you handle validation errors vs. system errors? Teams that standardize this write fewer bug-prone try-catch blocks.

Example pattern:

class ValidationError extends Error {
  constructor(message, field) {
    super(message);
    this.name = 'ValidationError';
    this.field = field;
  }
}

Then everywhere in your codebase, validation errors look the same. Code that catches them knows how to handle them.

Test file organization should match source files. If your source is src/features/users/services/auth.ts, your test should be src/features/users/services/auth.test.ts or in a mirror __tests__ directory. Same structure, easy to find.

Enforcing Conventions

Enforcement is where conventions live or die. The best convention in the world means nothing if it's only suggested.

Linters and formatters are the workhorses. eslint for JavaScript, black for Python, clippy for Rust—they catch style violations automatically. Make them strict enough to catch real problems. Be permissive about minor style differences. Run them in CI and fail the build if violations exist. Run them in the editor so engineers get immediate feedback.

A sample .eslintrc.json:

{
  "extends": "eslint:recommended",
  "rules": {
    "no-var": "error",
    "prefer-const": "error",
    "naming-convention": ["error", {"selector": "variable", "format": ["camelCase"]}],
    "no-unused-vars": "error",
    "eqeqeq": "error"
  }
}

Formatters like Prettier remove the need for style discussions entirely. They reformat code automatically. You don't choose how many spaces—Prettier does. You don't choose brace placement—Prettier does. This sounds limiting until you realize nobody actually cares about these details; they just want consistency. Run Prettier on save and in pre-commit hooks.

Pre-commit hooks catch violations before code reaches the repository. A tool like husky installs hooks that run linters and formatters before commits. An engineer can't accidentally commit badly formatted code.

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.js": ["eslint --fix", "prettier --write"]
  }
}

Code review templates remind engineers which conventions matter. Your GitHub PR template could include:

• [ ] Naming follows conventions (variables, functions, classes)
• [ ] Files are organized in the correct directory
• [ ] Error handling matches team patterns
• [ ] Comments explain why, not what
• [ ] Imports are ordered correctly

Documentation matters for conventions too. Write them down where engineers work. Not in a wiki that sits unused. In your repository README or a CONTRIBUTING.md file. Brief and clear.

Balancing Strictness and Flexibility

Too many rules and engineers waste time fighting linters. Too few rules and you get inconsistency.

The practical approach: enforce the ones that prevent real problems. Forbid var declarations in JavaScript—they create subtle scope bugs. Enforce semicolons? That's purely stylistic. Your formatter handles it anyway.

Distinguish between rules and conventions:

• Rules prevent bugs or security issues. Enforce them strictly. No unsigned integers without knowing why. No SQL string concatenation. No hardcoded credentials.
• Conventions improve readability. Enforce them, but they're not catastrophic when violated. Naming conventions, file organization, import ordering.

The golden metric: your team should be able to state why each rule exists in one sentence. If you can't, it's probably cargo cult rule.

Conventions and AI-Generated Code

When agents generate code, consistency becomes critical. An AI model that understands your naming conventions, directory structures, and error handling patterns generates code that looks like it came from your team, not an external source.

Agents can follow linting rules directly if rules are explicit. They can organize files according to your directory structure. They can use your standard error handling patterns. The clearer your conventions, the better the generated code integrates.

Training agents (or prompting them) with your conventions is like pair programming with someone who knows your codebase. They make fewer contextual mistakes.

FAQ

Primary Sources

• Robert Martin's handbook on writing clean, consistent code and naming conventions. Clean Code
• Martin Fowler's guide to refactoring for consistency and code quality. Refactoring
• Google's engineering practices on code style, standards, and convention enforcement. Google Eng Practices
• The Pragmatic Programmer's approach to standardization and team consistency. Pragmatic Programmer
• Steve McConnell's comprehensive guide to code construction standards. Code Complete
• John Ousterhout's philosophy on simplicity and consistency in design. Philosophy of Design
• Google SRE workbook on consistency, standards, and operational practices. SRE Workbook