I work in a control systems company, where the primary work is SCADA and PLC, along with other control systems stuff.
Software development is not really something the company does, apart from little bits here and there, until there was a decision to create an internal project management and appraisal system.
This project has been taken on by people who came here as software people originally and we are mostly junior.
The project started off small, so we only documented stuff like design, database stuff etc, but we never really agreed upon a coding format/conventions.
We started using StyleCop to make sure we had well documented code, but I feel we need an official document for coding conventions/practices so we can continue a good standard and if there is any more major development work in the future, whomever works on it has a good baseplate.
Therein lies the problem, I have no idea how to draft up a document for coding conventions and standards, all I can think of is examples of good vs bad practice (for example camel case when naming variables, avoiding Hungarian notation etc) we are all competent enough programmers (apparently) but we just don't have a charter for this kind of stuff.
To put a point on it, my question is: What are the key aspects and contents of a good coding standards document?
Best Answer
What are the key aspects and contents of a good coding standards document?
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.
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.
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.
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:
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.
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.
Microsoft's guidelines are well documented, so you don't have to write your own documentation.
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.