Software Design Document – Justification After Development

If the pros and cons can be summarized in a sentence or two, then it's OK to put them in a design document. Anything longer should be separated out.

Where I currently work, there is usually a separate "Design decicions" document to track all Big and Important decisions. Often formatted with a paragraph describing the problem (such as "Some files need to get moved from a server to certain users at the end of each processing cycle, there are many ways to do this..."), a table with columns "solution description" (such as "move files via FTP"), "pros" (such as "Easy for users to manage"), "cons" (such as "not secure enough for ABC-XYZ compliance") and a conclusion that explains why a particular decision was chosen (such as "FTP will not be used because it will not be able to meet certain compliance requirements"). The design document usually only references the chosen decision, and may recommend readers to read the decicion document for a full description of other options.

What are the key aspects and contents of a good coding standards document?

1. Being supported by tools which enable automated checking of the code. If I know that I can't commit to version control any piece of code which doesn't match some rules, I would be encouraged to follow those rules in my code. If, on the other hand, some fellow programmer have written somewhere that I need to follow a rule, I don't give a crap about those rules.

2. Being well thought-out, instead of being your personal opinion. You don't plainly say: "from now on, we don't use regions any longer, because I don't like regions." Rather, you would explain that regions encourage code growth and don't solve any major problem.

   The reason is that in the first case, your fellow colleague would answer: "well, I like regions, so I would still use them". In the second case, on the other hand, it would force people who disagree to come with constructive criticism, suggestions and arguments, eventually making you change your original opinion.

3. Being well documented. Lack of documentation creates confusion and room for interpretation; confusion and possibility of interpretation lead to style difference, i.e. the thing standards want to suppress.

4. Being widespread, including outside your company. A "standard" used by twenty programmers is less standard than a standard known by hundreds of thousands of developers all around the world.

Since you're talking about StyleCop, I suppose that the application is written in one of the .NET Framework languages.

In that case, unless you have serious reasons to do differently, just stick with Microsoft's guidelines. There are several benefits in doing it rather then creating your own standards. Taking the four previous points:

1. You don't need to rewrite StyleCop rules to fit your own standards. I don't say it's hard to write your own rules, but if you can avoid doing it, it means you have more time doing something useful instead.

2. Microsoft's guidelines are very well thought. There are chances that if you disagree with some of them, it might be because you don't understand them. This was exactly my case; when I started C# development, I found a few rules totally dumb. Now, I completely agree with them, because I finally understood why they was written this way.

3. Microsoft's guidelines are well documented, so you don't have to write your own documentation.

4. New developers who will be hired in your company later may already be familiar with Microsof's coding standards. There are some chances that no one will be familiar with your internal coding style.