ALM Practices Part 4: Common Code Layout

What is it?

A collection of rules stating what a block of code should look like. These may include rules on where line breaks are required, how to place parentheses, how much whitespace to put before and after those parentheses, how many spaces to use when indenting and where to insert empty lines.

Why would you do it?

• To allow developers to work on virtually any part of the code base without being confronted with another different layout. And even though this may seem like a feeble issue, I’ve seen firsthand how difficult it can be to navigate through a block of code which uses an entirely different layout.
• To improve the reviewability of your code base. For the same reason another developer benefits from it, the reviewer needs to be able to easily scan code for often-made mistakes or other issues.

What’s the bare minimum you need to do?

• Use a standard layout for the entire code base and remind everyone to adhere to it.

What’s the usual thing to do?

• Use a product such as ReSharper and configure it in such a way that it will format your code automatically according to the standard layout.

How do you do that?

• Together with your team, agree on a common layout and write it done somewhere such as your team site, preferably accompanied by a piece of example code that illustrates all aspects of the standard.
• If another team within the company has already created something like that, consider adapting their standard. This eases the burden when team members move from one project to the other.
• Consider buying a ReSharper licence and use its Code Style sharing feature so that all team members will automatically receive the most up to date version of the standard settings. It also allows you to reformat entire files, projects or even the entire solution with one click of the mouse.
• Create a one-page cheat sheet with a block of example code that clearly demonstrates the proper layout and distribute it amongst the team members. Use it while performing a Peer Review.
• Install StyleCop and use it for automatically checking the layout and the XML documentation according to a configurable set of rules.
• Add compliance to this standard code layout to the project quality Checklist (I will blog about that later on) so that developers and reviewers don’t forget to check for it.