Best Practices for Creating Change Lists in Code Development

As a part of the infrastructure team, I often find myself writing a significant amount of code. This could involve adding new features based on new technology or making extensive changes to improve the existing codebase. When we're making substantial changes to how our code is organized, managing it becomes just as important as writing the code itself. Over my ten years in this field, I've come to realize how essential Change Lists (CLs) are for debugging and keeping a record of all the changes made. It's widely known that dealing with one massive set of changes can complicate the process of handling code. Here are some tips that can make life easier, whether you're a programmer or a reviewer:

1. Isolate Changes in Independent Change Lists:

When you're making big changes to your code, a key principle is to separate those changes into independent Change Lists (CLs). Each CL should focus on a particular thing, like adding a feature, fixing a bug, or making an improvement. This way, it's easier for both developers and reviewers to understand what's going on in the code. It's like breaking down the changes into smaller, more manageable pieces, which helps keep the evolving codebase in check. Plus, it's handy for future reference. You can clearly see why a specific code change was made, thanks to the detailed and straightforward descriptions.

2. Ease of Code Review:

Splitting changes into smaller, specific Change Lists (CLs) makes the process of checking the code better. Reviewers can look at the modifications more easily, giving better feedback. Also, breaking down the changes lets different team members, who are experts in specific areas, review them at the same time. This speeds up the overall review process.

3. Simplify Testing:

Keeping changes separate helps in testing things more precisely and quickly. Developers can concentrate on testing particular features or fixes without getting tangled up in unrelated changes. This method ensures a thorough testing process, reducing the chance of missing any bugs and making the overall code better. It also means you only have to test the specific changes, saving time in the process.

4. Backward Compatibility:

Making sure things still work with older versions is super important, especially when you're working on different parts of the code at the same time. By keeping changes separate in Change Lists (CLs), it's easier to find and fix problems related to compatibility. This is really handy when you're moving those changes to older versions, as it reduces the chance of unintentional issues. Having limited changes in one place makes it much simpler to figure out and fix any specific problems in older versions.

5. Traceability and Root Cause Analysis:

When there are problems or tests fail, having separate Change Lists (CLs) is like having a super useful tool. Developers can quickly figure out exactly which change caused the issue, making it much faster to fix the problem. It's way harder to do this when dealing with big, all-in-one lists of changes. Specifically while back propagating.

6. Incremental Progress and Continuous Integration:

Making separate Change Lists (CLs) helps in moving forward step by step. Developers can add and mix in changes that have been tested and approved, showing progress in smaller parts. This matches well with the idea of continuously adding and updating things, creating a more flexible and collaborative way of developing.

Manish Joshi

Senior Software Engineer