Coding Standards Rollout Tool: Problem Background

As developers, we often inherit legacy codebases that lack consistent coding standards. In most languages we tend to have good tools to fix them in an automated way, freeing code reviewers up to focus on more substantive issues. However, rolling out coding standards changes needs careful management when a project is under active development. Widespread changes to all files may put ongoing feature development branches in a state of merge conflict. As part of a process moving towards coding standards checks/fixing built into the CI/CD pipeline, one step is to roll out changes to all files except those currently being worked on. As a contractor, I have done this a few times, and it has now reached the point where I have automated a solutioun to this problem and open sourced it. Let me introduce the Coding Standards Rollout Tool, and the process around it. Together, they provide a solution designed to ease the transition to modern coding standards in large projects while minimising disruption to ongoing development.

## A Plan for Fixing Your Coding Standards

What the Tool Does

This tool is specifically designed to apply coding standards across your entire project without interfering with files currently being worked on in feature branches. By doing so, it prevents merge conflicts and ensures that your codebase gradually evolves towards the desired standards.

Suggested Process for Introducing Coding Standards

  1. Clean Up: Remove obsolete branches to minimise edited files.
  2. Initial Run: Execute the tool to apply standards to all files except those which are edited in a branch.
  3. Merge Quickly: Merge quickly before significant changes are made in other branches.
  4. Continuous Updates: Encourage developers to update their branches. Rebasing now prevents conflicts later.
  5. Repeat: Run the tool periodically to capture stragglers.
  6. Automate: Integrate a coding standards fixer into your CI/CD pipeline once you feel it’s time.

Key Features

  • Non-Disruptive Rollout: Changes are applied to files not currently modified in any branch, ensuring minimal disruption.
  • Configurable: Compatible with any coding standards tool that can be executed through a shell command.
  • Repeatable Process: Designed to be run multiple times, gradually enforcing standards as feature branches merge and close.

How to Use

  • Configuration: Set up your configuration file (example provided in the repository).
  • Build: Compile the tool using make build.
  • Execute: Run the binary with the appropriate config file.

For detailed instructions and configuration examples, visit the GitHub repository.

Behind the Scenes: Building the Tool

Creating the Coding Standards Rollout Tool was a rewarding challenge. Although primarily designed for PHP codebases, I chose to write it in Go due to its performance and concurrency capabilities. The tool employs a worker pool approach to efficiently handle multiple tasks in parallel, allowing it to process a repository with 200 open branches in about 5 seconds. It is doing a git diff on a number of branches in parallel.

Test-driven development was integral to the process, ensuring robust and reliable code. By using spies as test doubles to represent Git system calls, I could test the business logic without side-effects. This methodical approach not only sped up development but also enhanced the tool’s reliability and performance.

Explore the repository to see the code, and feel free to contribute. Happy coding!

Conclusion

The Coding Standards Rollout Tool helps make your legacy more legible, without the disruption. By systematically applying coding standards, you can improve readability without getting told off for giving everybody merge conflicts. The process behind the tool gives you a path to getting coding standards fixing into the build pipeline. This can be done following the path of least disruption. Feel free to give it a try, and take a significant step towards a cleaner, more manageable codebase.