Return to Answer

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.

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 were 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 Microsoft's coding standards. There are some chances that no one will be familiar with your internal coding style.

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.

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.

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.

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.