Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I work in a control systems company, where the primary work is SCADA and PLC, along with other control systems stuff.

Softwre 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?

share|improve this question
2  
Do you already have comprehensive test coverage? Doesn't matter how pretty the code is if it is wrong... –  JBRWilkinson May 1 '13 at 12:14
1  
The good thing is we throughly test our stuff, we have regular unit testing implemented for our project, and we before releases we will use random hallway testing, and write a test spec for black and white box testing. –  Felix Weir May 1 '13 at 13:26
    
The priority our little group holds is our code is robust and can't be broken. We also use bugzilla for bug tracking, and a custom bug reporting tool for users. –  Felix Weir May 1 '13 at 13:32

4 Answers 4

up vote 10 down vote accepted

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, instead of being your personal opinion. You don't plainly say: "from now, 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.

share|improve this answer
    
We have version control (SVN, hoping to move to GIT soon), and the lead of the project always reminds us to regularly update then commit to avoid mass conflicts (at least a couple of times a week). –  Felix Weir May 1 '13 at 13:30
    
BTW, you mention "tools which enable automated checking", which tools are these? I am curious. –  Felix Weir May 1 '13 at 13:30
    
@FelixWeir: for .NET Framework? StyleCop. –  MainMa May 1 '13 at 14:06
    
Oh right, I thought you were hinting at something else. We use Stylecop... :^) –  Felix Weir May 1 '13 at 14:28
1  
@FelixWeir: also, try (if you haven't done it already) Code analysis. The purpose is different and not related to style itself, but it also enables standardization. –  MainMa May 1 '13 at 14:46

I was going through this process multiple times. And the most successful (although bumpy anyway) was approach was to take "Coding Standards" document from well known company and modify it to fit your needs.

For example, I just found this one: http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

Anyway, keep your flame-thrower handy.

Cheers,

share|improve this answer
1  
+1 I was going to say the same thing. Creating a coding standards document is a huge job which has been done before. Find a good one , then amend to customize. –  John MacIntyre May 2 '13 at 8:12

The first important thing to note is that a coding standards document is not about right and wrong. It's not about good and bad or which method is better.

A coding standards document's purpose is to make sure that all code is designed, written and laid out the same to make it easier for a developer to switch from one persons work to another without the needed change of mentality to read someone else's style.

It's all about uniformity, and nothing about "Right and wrong"

With that in mind some things you should clarify in a coding standards document are:

Naming Conventions

How will you name your methods, variables, classes and interfaces? Which notation will you be using?

Also something else included in our standards was a split off standards for SQL, so we had similar names for tables, procedures, columns, id fields, triggers, etc.

Indentation

What will you be using for indentation? A single tab? 3 spaces?

Layout

Will braces be kept on the same line as the opening method line? (generally java) or on the next line or a line of its own? (generally C#)

Exception Handling / Logging

What are your standards for exception handling & logging, is it all home grown or are you using a third party tool? How should it be used?

Commenting

We have standards to dictate grammatical correctness, and that comments begin on the line before, or after, not on the same line, this increases readability. Will comments have to be indented to the same depth as the code? Will you accept those comment borders used around larger texts?

How about the \\\ on Methods for descriptions? Are these to be used? When?

Exposure

Should all of your methods and fields be implementing the lowest level of access possible?

Also an important thing to note. A good standards document can go a long way in helping review code, does it meet these minimum standards?

I've barely scratched the surface of what can go into one of these documents, but K.I.S.S.

Don't make it long, and boring, and impossible to get through, or those standards just wont be followed, keep it simple.

share|improve this answer
1  
Coding standards often, especially for C/C++ development, also contain a (large) section about which language constructs you should not be using and why. –  Bart van Ingen Schenau May 1 '13 at 12:56
1  
@BartvanIngenSchenau there's no reason why you need them for C++, or why you don't need similar sections for other languages - you can make a mess out of C# or JS or .. well, anything. All languages have 'features that can be misused'. Best to train your devs to be good at their job instead of filling the standards document with "how not to code" mini tutorials. –  gbjbaanb May 1 '13 at 14:54
    
@gbjbaanb: I can't comment on other languages, but C++ has enough dark corners and pitfalls that it is not about avoiding mis-use, but rather steering people away from the features that are difficult to use correctly (for example, overloading of &&). Training is good, but sometimes it is better to have a nice reference document to refresh your memory why you should not do that. –  Bart van Ingen Schenau May 1 '13 at 15:35
1  
@BartvanIngenSchenau i feel that would be better placed in a Coding Guidelines Document, not a Coding Standards Document –  RhysW May 1 '13 at 15:39
1  
+1 "It's all about uniformity." –  SShaheen May 1 '13 at 18:23

I hate most standards documents as they usually try to sweat the small stuff and ignore the bigger picture.

For example, nearly all of them will say how to name variables or place brackets. This is pure style and does little to really help a group of devs code correctly. They ignore stuff like directory structure and code layout. I've seen standards documents that told you exactly how many spaces to put between operators and how many blank lines to put between methods. All of these usually end up with a ton of exceptions to the rule which just shows how pointless they really are, and then they are so big no-one can follow them, which again, makes a mockery of the point they are trying to make.

Now for me, I use many different bits of software from lots of different people and they all have different styles. I simply get used to this, I don't complain that there isn't a common style across all development groups. As long as the code is a common style throughout a project, I really don't care what that style is. So my first rule for all standards documents is: Keep a consistent coding style within the project. no-one should give a fig where the brackets are, as long as they are all the same. Take the religious wars and shove them :)

The second is code layout. When I pick up a piece of code, I want to see that its laid out along similar lines as other, similar pieces of work. If I have a web service I want the name of the wsdl contract to be clear, I want the name of the implementation to be clear. I do not want someone to come up with a brand new and different layout for files and classes. That means I have to play "hunt the code" which is a nuisance. If it looks the same as the last project I worked on, I can immediately know where to find what I'm looking for and it is probably the biggest help to working with other people's code that I know. So, keep a structure of how the code is laid out (eg Documentation folder for docs, interfaces for interfaces etc - whatever it is that works for you, but stick to it).

Code artifacts should be present too, so you need to say whether the expected error handling is exceptions or error codes - ie. document architectural functionality that's in use. It should also say what kind of logging to use and how to present logs/error handling to the user or whatever subsystem is used to manage code in the wild. I worked in a place where every project did logging differently - it was pathetic how each code release had to have its own, different, operations document telling the ops guys how to tell if it had gone wrong. Event log, log file (in which case where), etc are all valid here. The same applies to other common aspects to code - how to configure it (no point using a .config file for some programs, or a custom DB, or command line params, or registry for others).

In short, the only thing that matters is Consistency. And as huge standards documents are too much to read and memorise, I prefer to just inform people of the stuff they cannot see (eg architectural standards like logging) and tell them to keep the code they write consistent with what is currently there. And if you don't have code already then you don't need a standards document! (well, not until you've written enough to make it useful).

So take from that the main points: don't try to make a legal document, think of things that aren't just coding but also how the code works and how the code fits with other people's expectations. Then trust people to do good code and you'll see that they do. (and if they don't you can have words with them, no need to lay it down like law).

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.