Coding Standards, Team Development, and You

by Peter A. Bromberg, Ph.D.

Peter Bromberg
“There is no such thing as a wrong note.” --Art Tatum

I've written about this general subject several times, as early as this piece from 2002 on Team Development. When I was a Development Department manager for a period of some months (until I came to my senses and asked to be put back in as a developer), I made the Team development Whitepaper that you can download from that article mandatory reading for every developer in the group.

I complained some time ago about having to work on two web projects where there are now not one or two, but FOUR separate generic SQL Server Data Access classes, all of which do essentially the same thing.

They all do it differently, because individual developers have taken it upon themselves to "roll their own" without consulting with the team about best-practices coding standards and what we already may have, or not have, to work with. A lot of times you’ll work in a shop where various contractors are brought in, and nobody takes the time to explain “how we do it here”. Not only that, since they know they won’t be there long, their sense of responsibility to the overall success of the project is reduced. Why did they do it? Simple. Management doesn't necessarily think that coding standards for the development group are that important. They're wrong! I know, because I've been in these environments enough times to know the difference, and I have been a manager too. A good manager doesn't just make sure his or her people observe good team development and coding standards, she also has a clear vision of the architecture and functionality of the overall project.

What makes it even more exasperating is that each developer has cobbled in references to their own little pet assemblies which in most cases have no business at all being dependent assembly references to a very generic "talk to Sql Server" class. In one case it was the Anthem.Net library, which really belongs -- on the Toolbox!

In addition, developers have taken it upon themselves to use hard references to assemblies in some shared folder, rather than project references, even though most everyone has these various projects on their hard drive, hooked up into source control. Usually there is no excuse, or the lame comment that "it takes too long to build otherwise". Jeesh! Ever heard about Buld Configuration and just turning off the build action on stuff you don't need to be rebuilt?

I had a fellow developer tell me recently that so far as he knew there were no coding standards, but it's kind of  hard developing a standard when everything is rushed when needed. so as for web developing, “things just need to get done as soon as possible”.  Actually, having sound coding standards and processes that everyone can “buy in to” speeds up the development process!

When I worked at a banking software firm back in early 2001, doing our first big .NET project with Microsoft support, we had 17 developers in two teams working together. We all sat down in the conference room at the very beginning and argued –- for hours -- and we all agreed to use the "SqlHelper" class from the Microsoft Data Access Application Blocks sample code for our basic "talk to SQL Server" needs. We chose it because it (at least, at that time) exemplified one of the most important fundamental principles of framework design: it had been constructed by focusing on a set of common usage scenarios to enable power and expressiveness, and especially, ease of use. The learning curve, even for beginners, was fast, the class was well-documented, and it offered features (such as automatic static caching of SqlParameters) that I would never have thought of at the time. Most of the methods take care of disposing and closing of connections automatically, and the ability to make a Sql Server stored proc call with a simple object array of parameter values makes most database operations simple "two - liners" - saving sometimes 10 to 30 lines of "BS" code.

I cannot describe how much easier that made things. Everybody was doing Sql calls the same way; you always knew exactly what their code was doing, and you never had to look for assemblies that you had missing references to, because THERE WAS ONLY ONE.

Now if you wanted to build a specialized DAL, you could still have it use the SqlHelper class under the hood for your basic data access, and so you weren't restricted in any way. It saved us literally dozens of hours of developer time and, you know what? I still use it today (even the more advance Provider model version) - five years later. As a matter of fact, in five years, the only thing I've found missing in the SqlHelper class is a way to set a custom CommandTimeout - which was easy to add. Are you C# - challenged? No problem -- Microsoft puts out a VB.NET version too.

My point is -- It doesn't have to be "SqlHelper" - it can be any basic data access class you want, provided it has been engineered to fit your team's needs. But, it should be the same for everybody, and if it needs to be able to do something new, then everybody should get together on that before making the change. And the framework should be designed properly. If you want to study good framework design basics for class libraries, a good place to start is Framework Design Guidelines by Krzystof Cwalina and Brad Abrams.

Man, I hate to sound like a broken record, but really - this is such basic stuff, it just blows me away how people don't seem to think that this is important. It's VERY IMPORTANT! We do not do our development in "a vacuum" -- even if we are the only developer on a project. Other people have to be able to use our code!

Is your development process "Broken"?

Recently I was asked to add something to an internal web project that has gone through a number of iterations and also a number of developers. I spent the better part of an afternoon, and part of the next morning just getting everything out of Visual Sourcesafe to build. I complained, because most of this was due to either developer lack of knowledge, lack of professional standards, or just plain "don't care". This is a list of some of the initial recommendations I made when asked:

List of items that should be fixed with development process:

1) Developers should always arrange their projects, solutions, and the way they are source controlled with a view toward making it easy for new developers to be able to begin work on the solution with the minimum amount of hassle. This includes:

a. Put 3rd party assemblies in the solution as Solution Items and have them checked in with the solution so that people don't need to set mapped drives to shares containing libraries. These can be easily updated and developers can Get Latest to stay in sync. If you decide you have to use a mapped drive for your custom assemblies in order to cut down on the number of projects in a solution, make it a virtual one (e.g. "X:") so that it is portable if a machine changes. Make sure your build script or however you do your updates always updates this folder with the latest builds daily.

b. Make all references PROJECT references. If the developer already has this project from Sourcesafe on his hard drive, it will synchronize automatically from Sourcesafe, they will not need to get a separate copy. Keep all the PROJECTS that are used WITHIN THE VISUAL STUDIO SOLUTION whenever possible. Project references allow you to debug through different projects in the solution, and they also enable you to keep changes made by members of your team synched-up.

c. Name your solutions appropriately in Sourcesafe so that new developers will not mistakenly get the wrong version or one that is not being used.

d. Name your Projects and the namespaces of your classes in a project consistently. don't have namespace Foo.Bar in project named Blat.Bork, and then have another project in the solution that looks like "Foo.Bar"!

e. Do not alter the default build outputs of a project. Project output is normally directed to the /bin/debug or /bin/release folder.

f. Correct any and all compiler errors and warnings, even if they do not prevent successful compilation. If the compiler says Not all code paths return a value then FIX IT before checking in your code. If the compiler has a warning about an ambiguous cast, FIX IT. If the compiler says a variable was declared but never used, then FIX IT. There is NO REASON why a professional developer cannot have a Solution that has NO WARNINGS after it is built.
g. Check in all code but only if it builds and has been tested first. Use comments so other developers can see what changes you did. Did you test to see if OTHER PARTS of the Solution haven't been broken by your changes? You'd better!

h. Set all Assembly versions to “” ( a fixed number)  in the assemblyinfo.cs file, not 1.0.*.*. This prevents overwrite errors because of automatic build number incrementation. If you really have a New Version then you can  hard code it in. And, you better make sure that when everybody else does a “get latest”, they’ll get it.

2) A new developer should be able to tell Visual Studio to open Solution from source control, download all the projects, compile and build the project within 20 minutes. If this cannot be done, either your source control arrangement is not acceptable, or your developer team has not been educated in the above concepts, or both.

3) Whenever possible ambiguities and misunderstandings about projects, naming conventions and other similar items can cause problem, it is incumbent on each developer to think about the other people who may need to work with their code and take appropriate steps to ensure that their development experience goes smoothly. Usually this is simple common sense, and asking the question. "What does this affect?"

There is nothing that PISSES ME OFF more than a shoddy development team effort that reflects a lack of planning, discipline and basic rules of the road. If I were the boss and you did this stuff on my team, YOU WOULD BE GONE. If you haven't read the Team Development Whitepaper, here's the link again. Once again, if you worked for me, this is required reading before you can write one line of code on my team!

A mediocre standard is better than no standard

Bruce Wood, a frequent poster on the MS C# newsgroup, said it all:

"A mediocre standard is better than no standard at all"

Bruce was responding to an OP's desire to "innovate" by using a non-standard implementation of event handlers, and he recalled his experience at university where his professor asked, "What is the purpose of writing code?". After the usual answers (e.g. "To make the computer perform some task") he answered, "It's to make it clear to the next guy that reads the code how you solved the problem".

The point is, if the only objective is to make the computer perform some task, why not just use assembly language?

The answer is that in a multi-developer environment, or even one where you may someday leave and someone else will take over your code, you want to make it as easy as possible for others to understand not only what you did, but how you did it, and to be able to maintain that code. It is common for the insecure programmer to want to be the deus ex machina of the organization. As developers mature they usually learn that good teamwork and sharing of coding standards is far more important.

Bruce finishes, "Hacking out funky code 'that works' costs your employer extra because it will be more expensive to maintain.... A good programmer will make it work, and make it clear how it works so that it's easy to fix and modify in the future. That's what separates the professionals from the dillettantes".

Often we as developers learn some new technique and become so consumed by "how cool it is" that we forget about Bruce's principle. And, often as not, we don't think through the other implications, such as performance considerations. For example, dynamically compiling custom assemblies based on business rules that come from a database and dynamically executing these using Type.InvokeMember semantics may be very cool, but as Joel Pobar points out in his MSDN article, if that technique is in your application's "fast path" (e.g., it gets called repeatedly) you may end up finding that you have shot yourself in the "Code Monkey Foot", so to speak.

Another sore issue is exception handling. If exception handling isn't standardized across a development team, the result is often that a great deal of additional time needs to be taken during the coding and testing process. I've seen several examples of code in our group where developers basically make the code "swallow exceptions" ( e.g., try { ... } catch { // nuttin' } ). This is reallyreally EVIL! Another thing they do is return or populate some sort of "Error" property in their class. No, Man! What am I, talking Greek or something? If there's an exception then THROW THE SUCKER! Let the caller code defensively and be prepared to handle it. Their dumb code is supposed to give me a DataTable and now instead, I get back nothing and then I'm supposed to be telepathic and know that I have to check some Error property that they've put on their class, which has no documentation at all? Who codes like this crap? I mean, that's just the beginning, it gets even worse! Iceberg ahead, what do you say we rearrange the deck chairs, huh? The worst effect of little or poorly developed coding standards is the "monkey-see, monkey-do" phenomenon where developers simply copy the bad practices of previous coders. The way you stop this is to simply NOT ALLOW bad practices, and for that, somebody good has to do code reviews. Of course, if you have no coding standards, then it's unlikely you have reviews, right?

Feel free to make your comment below. I can take it. It's been a rough day...

Peter Bromberg is a C# MVP, MCP, and .NET consultant who has worked in the banking and financial industry for 20 years. He has architected and developed web - based corporate distributed application solutions since 1995, and focuses exclusively on the .NET Platform.
Article Discussion: