Coding guidelines for seamless merging

Question

I am looking for coding guidelines developers should follow while writing C#/ASPX/SQL code, so that merging into other branches is smooth if not seamless.

Answer 1

It's more a matter of proper SCM usage than coding style. However, a few coding style specific guidelines should be followed:

• Avoid long lines, especially lines that do more than one thing (and are thus more likely to contain more than one edit)
• Avoid overly long blocks (functions, classes, nested blocks, etc.)

And SCM-usage wise:

• Pick a good SCM. The world's most popular one (Subversion) is, unfortunately, not a good one.
• Branch liberally (this is why you need a good SCM: bad ones make branching and merging unnecessarily hard).
• Commit often. If your commit touches more than one implementation step, you're doing it wrong.
• Pull and catch-up-merge often. The later you integrate other people's changes into your own line of development, the more confused the SCM will be.
• If you feel you have to reindent, reformat, or refactor, do it in a separate commit and mark it as such.
• Never put anything under source control that can be derived from something else - this means no binaries, no generated code, no build intermediates, etc.
• As far as SQL scripts go, opinions differ, but IMO, an SQL script, once committed and pushed, should never be touched again (unless it is buggy to the point that it doesn't execute at all). Also, set up a procedure that makes sure everyone runs the right scripts, and never runs them twice. Keeping a list of scripts already executed in the database, and a list of all scripts to be run in source control, is a simple yet effective way, especially because the to-be-run list can be branched and merged like any other source file.

Answer 2

Provided you're team is working on the trunk rather than doing feature branches. Martin Fowler will tell you they're bad in this article

Ensure that:

• everyone uses the same set of standards, especially if they're set in the IDE so that it does the formatting for them.

• the commits are done regularly so that merging happens often so the merges are small. developers are following solid principles (classes and methods are small) so developers are not working on top of each other.

• the team communicates so major renamings, moving of packages, etc can happen when everyone knows about it.

Then you shouldn't have too much pain in merging.

Answer 3

Take the "If it ain't broke, don't fix it" mantra even further - if it is broke, fixing it will cost the time to fix and the time to fix the merge conflict. Most of the time you will get lucky, and not have a merge conflict. The rest of the time, you will want to be really sure the pain was worth it.

i.e. If you don't like the formatting, learn to live with it. Don't make changes that are not material to the feature that you are working on.

Answer 4

so that merging into other branches is smooth if not seamless.

I don't think coding guidelines per se will be very helpful, but some best practices in using your chosen version control tools will help:

• Avoid having two people modify the same section of code at the same time. That's not always easy or possible, especially on larger teams, but multiple simultaneous modifications of the same code is what creates merge conflicts.

• In furtherance of the previous point, merge your work as soon as is practical. Don't wait a week to merge if you're done now -- you want to keep the window during which someone else might modify the same code that you worked on as short as you reasonably can.

• Learn to use your tools effectively. Merge conflicts will happen, and merging will seem a lot more "seamless" if you know how to resolve them. It'll help if you create some toy projects and create conflicts on purpose. Do you know how to resolve a tree conflict? Can you roll back to a previous version? Can you merge changes between branches?

• Coordinate. If two people do have to work on overlapping sections of code, have them coordinate with each other. If they know what they're doing, they can share changes with each other during their work so that there are no surprises at merge time.