Tips to make your codebase future developer friendly

June 15, 2023

Starting work on a new codebase presents challenges, especially when predecessors leave behind poorly maintained code. These practices help create codebases that future developers will appreciate.

Language Version Constraints

Specify language versions as dependencies rather than relying on potentially outdated documentation. Add version constraints to dependency files so installation fails when versions don't match requirements.

For PHP with Composer:

"require": {
  "php": "~8.0",
  "ext-dom": "*",
  "ext-json": "*"
}

JavaScript/Node with NPM:

"engines": {
  "node": "~16"
}

Deploy Automatically

Manual deployment introduces error risks. Automation eliminates these risks consistently, even for small projects. Recommended tools include Deployer for PHP, GitHub Actions for CI/CD workflows, Serverless for Lambda functions, Bref for PHP serverless support, and Terraform for infrastructure management.

Code Style

Adopt opinionated formatters like Prettier to enforce consistent styling automatically. We prefer consistent code style over the ability to tweak code style. This offloads responsibility from developers to tools. Prettier supports JavaScript, JSON, and YAML natively, with plugins available for PHP and Go templates.

Static Analysis

Static analysis tools identify code issues and promote robustness. PHPStan works effectively for PHP projects, running on every push. Rather than immediately achieving maximum strictness levels, start modestly and incrementally increase standards.

Sort Lists Alphabetically

Alphabetical sorting for constants, classes, routes, and similar elements provides clarity. Alphabetical sorting benefits readability, clarifies where new entries belong, and reduces Git merge conflicts.

README File

READMEs serve as essential starting points. Include stack information, project history, documentation links, design links, ticketing system references, local setup instructions, user creation processes, testing procedures, and data seeding methods. Write assuming readers lack project knowledge.

Solve Warnings

Warnings deserve attention despite not being errors. Deprecation warnings signal upcoming removals. Addressing warnings prevents developer confusion consuming valuable time. Document unsolved warnings in README setup sections.

Add a Working .env.example File

Provide developer-friendly environment variable defaults to streamline setup. Limit defaults to essential variables like database configuration. Keep email using log drivers, caching using array drivers, and queues using sync drivers by default. Enable specific services only when developers work on related features.

Unit Tests

Unit tests ensure code functionality while serving as documentation. Reading the unit tests gives a lot of insight into the project and its features. Write tests as narratives focusing on features rather than classes or coverage percentages.

Comments

Clear code with descriptive naming helps readability, but complex business rules, backwards compatibility, and legacy code sometimes require explanation. Comments should explain "why" code exists as written.

Use Long Flags in Shell Scripts

Replace cryptic short flags with descriptive long flags. Instead of tar -xzf file.tar.gz ., write tar --extract --gzip --file file.tar.gz --directory .. This improves readability for developers unfamiliar with commands.

Originally published on norday.tech.