Coding Style and Stylecop

How important is coding style? This debate is something that really draws out the "artist" and critic in every programmer. In many ways the style of writing code is similar to writing poetry, and what makes the subject so hotly debated is that the beauty of the code, sentence or poem is all in the eye of the beholder. Just like those critics of of prose and poetry, the serious critiques of coding style come from understanding the limits and history of the form. Practice reading and writing lots of code, in different languages if possible, and acknowledging how many ways there are to write the same functionality.

In the same way that experimentation in poetry and prose makes for a better understanding of the overall form, understanding how different coding standards can make for better (or worse) code. With every coding standard the code will be limited but also potentially clarified in a new way.

Organization of code one way can make code reviews easier, but potentially making maintanability more difficult, code may be separated into different sections that are ordered in a certain way that causes significant scrolling, opening of multiple files and jumping through layers of code, that structured a different way may minimize bouncing around.

Coding standards for teams is especially important, and should be strictly adhered to as best as possible, for the overall benefit of the team. Consistency is very important as being able to quickly jump into a new class, module or section of the code "should" be as easy as jumping into a section that you wrote yourself. Coding standards are an agreement between programmers to create a cohesive work, much like any collaborative effort, the final product should be a uniform work of art.

The most diplomatic way to handle this is often through adopting a tool that lets catches errors quickly and consistently. This also frees up code reviews to be on more important aspects like architecture, re-usability, error checking, design patterns etc. as non-adherence to coding standards often ends up becoming the main focus if the code strays too far from the standards outlined. These tools should also be part of the commit process, so that the code is rejected if it does not pass the coding standards (in certain cases some of these tools may have to have slight adjustments, as desired, but with a focus on consistency).

For those C# Unity or XNA projects some guys really like Resharper (30 day trial at http://www.jetbrains.com/resharper/) For a free style specific checker I like StyleCop: http://stylecop.codeplex.com/ there is a good amount of customization and easily embeds into Visual Studio. The information that is provided from the code checks make it easy to know the issue and change the code to follow the coding standards that have been setup.

For python there is pep8 http://pypi.python.org/pypi/pep8 and pychecker http://pychecker.sourceforge.net/ as well as a few more.

In general the style and syntax checkers are becoming quite popular (especially with scripting languages that don't compile) but regardless a good "style cop" will improve code quality, readability of all sections of the code, and allows everyone to focus on writing great code, instead of what it looks like in the end.

Until next time, StyleCop: that is all.
Michael Hubbard
http://michaelhubbard.ca

Book Review: C++ In Action Industrial Strength Programming Techniques

With all the posts on Agile methodologies I decided to take a break and follow up on more programming aspects. C++ In Action Industrial-Strength Programming by Bartosz Milewski is as the preface states "... is not a language reference or a collection of clever tricks and patterns. This book is about programming." The book offers some useful insights into those programming coming from a C or Java background, but ramps up with some important theory of programming, with useful examples for function pointer routers, techniques for data encapsulation with templates and the windows API.

One of the ideas that struck a chord with me was the case against "defensive programming". Often programmers want to be as careful as possible, but by writing very defensive code, they end up writing nice little places for nasty bugs to hide. Milewski recommends using asserts on parameter input instead of attempting to handle invalid input at all, which in turn prevents bugs from "covering their tracks". He goes on to recommend that programmers do not try and write code that works no matter what. By attempting to write such defensive programming the code becomes more obscure and prone to errors. Instead, programmers should take an approach of validating parameters (and using asserts) and not attempting to handle invalid data by passing on more invalid/garbage data.

I really can get behind this concept, and often will try and write code that does a lot of error checking with quick returns. I find that defensive programming often also goes along with lots of nested if statements and tree logic that ends up complicating the code. The programmer wants to be defensive but does not check the parameters ahead of time, and instead complicates the overall structure of the code. Here are two simple examples of stuff I see all the time. The "Foo" example (below) is not uncommon to see, even though the "Bar" is easier to read and does the exact same thing. By focusing on validating parameters you end up with shorter, cleaner code which is much easier to understand and debug.

// Foo function (with valid inputs do the foo).
int Foo(Object obj, int param1, int param2, bool param3)
{
 if(obj != NULL)
 {
  if(param1 < param2)
  {
   if(param3)
   {
    // Do the foo.
    return 0;
   }
   else
   {
    return -1;
   }
  }
  else
  {
   return -1;
  }
 }
 else
 {
  return -1;
 }
}

// Bar function (with valid inputs do the foo).
int Bar(Object obj, int param1, int param2, bool param3)
{
 if(obj == NULL || param1 > param2 || !param3)
 {
  return -1;
 }

 // Do the foo.
 return 0;
}

The book is also available at http://www.relisoft.com/book/index.htm and while it does deal with a lot of different elements (like windows specifics, team work and porting code) the end result is an interesting read with some good looks on program transformation and improved structure.

I hope to get more real code examples up soon and will hopefully have some interesting content of my own. But until then I remain...
Michael Hubbard
http://michaelhubbard.ca