Brennan’s Blog

Sometimes when I work with other developers I inevitably find that all of the code looks different. Some developers like to write really compact code, as if we were still working on cartridges when disk space for the source code really mattered. Some developers also firmly believe that fewer lines of code in C# means it will somehow run faster because doing 5 things on a single unreadable line of code will somehow run in a single instruction in compiled code versus carefully expanded and readable code that performs the same 5 actions. I am not a fan of compact code. I prefer readable and verbose code with the occasional comment to help explain a bit of code that implements some strange business logic that was defined in the specifications but is not obvious from looking at the code.

Some developers will argue, and rightfully so, that inline comments should be few. Well written code can and should be self documenting. A method that is 500 lines long that carries out 30 actions with complex business logic is not readable. When that code is refactored into several methods averaging less than 30 lines of code each with accurately named method names the code suddenly becomes readable and self documenting. It also happens to become more reusable for the methods that contain logic that can be useful from other methods or other classes.

Once the code is broken up into understandable pieces I then like to have it formatted consistently. I do not want the "personality" of each developer on the team to come through in their code, just like I want every page on MSDN to show code in a format that I am accustom to seeing. I do not want to see clever indentation style that only one developer understands or various naming conventions for variables, methods and events. And I do not want to see opening and closing brackets to be formatted differently. I want the entire code base to appear as if a single developer had written the entire application.

In chapter 4 of The Mythical Man Month there is a note on architecture that I have often thought about when reviewing code that is inconsistent:

Most European cathedrals show differences in plan or architectural style between parts built in different generations by different builders. The later builders were tempted to "improve" upon the designs of the earlier ones, to reflect both the changes in fashion and the differences in individual tastes. So the peaceful Norman transept abuts and contradicts the soaring Gothic nave, and the result proclaims the pridefulness of the builders as much as the glory of God.

The chapter goes on to explain one cathedral, Reims, which was built over the course of 8 generations of builders who maintained a consistent design from start to finish. The integrity of the structure built with the consistent design is breathtaking to visitors who can see the consistency throughout the structure. The design also serves the structural needs of the cathedral beyond just the aesthetics. In software design the aesthetics of code the users will never see is not a driving force behind development, but ease of maintenance of that code to fix bugs or add new features is facilitated by a design that is consistent to the point that it reduces the learning curve for a developer jumping onto a project they have not worked on before. For projects that constantly implement new ideas throughout the life of a project there is a continual mismatch on what the developer can assume should work as they expect. As a result more mistakes are made or the time to complete the project without mistakes increases.

When writing code I follow a few personal rules:

1. Assume I will not be the only developer working on this code now and in the future
2. Use the C# default settings for indentations and brackets in Visual Studio
3. Follow the C# Coding Standard defined by IDesign.NET (with limited exceptions)

After following these simple rules I still find I need to reformat code. You can start by pressing Ctrl+E, D for the whole document or Ctrl+E, F for the selected region. When you format code with these key sequences it will help clear up extra whitespace at the end of lines after the semicolon and fix indentations, but it will not correct opening and closing brackets. By default the C# settings in Visual Studio cause the opening and closing brackets for code blocks to be on separate lines. Entering the closing bracket and pressing enter will actually move the opening bracket to the line in the case of a method or property definition. Moving the opening bracket has been useful to me but manually reformatting a file that is not structured this way is not adjusted by the key sequence mentioned here. Instead you can cut the entire code file and paste it back in place and that action will adjust all of the opening and closing brackets with your default C# settings. It is a very quick way to make all of the code in a project appear consistently.

Beyond this tip, I have considered using the Code Style Enforcer which was built with the C# Coding Standard in mind. When I have worked with developers who have used this tool before there were issues with it slowing down Visual Studio to the point it was not worthwhile. It would also raise many false warnings in perfectly valid code. One example is underscores in method names which are common in automatically generated event handlers in ASP.NET code.

I have not tried the Code Style Enforcer lately. Perhaps the performance is acceptable now, although at times I find Visual Studio 2008 has performance problems enough out of the box, even with the hot fix. For now I will just stick to my default C# settings and cut/paste code to achieve an acceptable level of consistency with minimal effort.