Holiday Goodie Bag: Free C# and VB Coding Standards Reference Documents

by on December 22, 2008

Over the years, I've had the pleasure (and sometimes pain) of being involved in writing and maintaining the internal coding standards documents for nearly every company I've ever worked for. I still have vivid memories of many bloody internal disputes over some really silly things  - where the curly braces should go - whether or not to use underscores in front of member variables. I firmly believe you need them to keep a consistent level of code quality and to this day I will still dig in and fight for this cause. The biggest lesson I've learned:

"It doesn't matter what the standards are, as long as you have them and everyone agrees to adhere to them!"

I present to you the latest incarnations of my efforts: a zip file containing C# and VB.NET editions of my reference coding standards. I've been holding these for the holidays so that I could share a little something extra with my readers as the year winds down. I certainly don't expect everyone to agree with my standards but I hope by posting these, you can get a head start towards documenting your own.

Grab them. Customize them. Share with your friends.

 

Translated editions:

Portuguese by Eduardo Costa



Comments

December 31. 2008 11:03

pingback

Pingback from mdosman.us

Free C# and VB Coding Standards Reference Documents | Mohammed Osman Blog US MS IT Hyderabad India

mdosman.us

December 31. 2008 11:15

pingback

Pingback from murratore.wordpress.com

Daily Blog Post 12/23/2008 « Murratore’s Weblog

murratore.wordpress.com

December 31. 2008 11:50

bvsmohan

Useful documents,
nice work

thanks

bvsmohan

December 31. 2008 12:01

Roger

Excellent! My team is missing this type of document and making them adopt one is going to be a pain in itself. Discipline is hard to build from the ground up.

Roger

December 31. 2008 12:19

Jahedur Rahman

Hi

Thanks for this guidelines. It would be great if you publish the files in .pdf format.
Another thing in Country "Bangladesh" is not specified. I am from Bangladesh Smile

Thanks Again

Jahedur Rahman

December 31. 2008 12:30

trackback

Trackback from Korea Evangelists

C# and VB.NET code standard document

Korea Evangelists

December 31. 2008 12:38

Piseth

Great, Nice tool to dig your .NET Land.

Piseth

December 31. 2008 12:39

rob

well done, thanks for sharing!

rob

December 31. 2008 13:05

Jay

This is some great stuff.  I can definitely use it to drive efficiency.

Jay

December 31. 2008 13:11

Nilufar

Thanks

Nilufar

December 31. 2008 13:25

pingback

Pingback from hectorperez.wordpress.com

Documentos de Nomenclatura para escribir código en C# y VB « Héctor Pérez Weblog

hectorperez.wordpress.com

December 31. 2008 13:28

pingback

Pingback from mtycoders.com

mty.Coders  » Blog Archive   » Documentos de Nomenclatura para escribir código en C# y VB

mtycoders.com

December 31. 2008 13:41

pingback

Pingback from ebnerj.at

Free C# &VB Conding Standard Reference Documents at Programming with Silverlight, WPF & .NET

ebnerj.at

December 31. 2008 14:10

Satalaj More

Thanks

Satalaj More

December 31. 2008 14:12

trackback

Trackback from US ISV Developer Evangelism Team

Customize and Share C#, VB Coding Standards With Friends

US ISV Developer Evangelism Team

December 31. 2008 14:23

Joe Walling

Thanks.  I am updating our company's development standards/guidelines and had missed a few of the items you included.

We agreed on most of the .NET coding standards but when we got to the database standards and use of ORM tools it got heated.

Joe Walling

December 31. 2008 14:25

Ashraf Nadi

Gr8 Gr8 Work Thnx

Ashraf Nadi

December 31. 2008 14:42

Bita

Thank you a lot for sharing your valuable experience with us.
It was a long time looking for something like it.
Good luck Smile

Bita

December 31. 2008 14:43

Adem Gashi

Thank you very much. I appreciate your work.

Adem Gashi

December 31. 2008 14:49

Stacy Vicknair

Thanks for the reference documentation! This will come in handy and the layout is great.

Stacy Vicknair

December 31. 2008 16:10

keith

Great work.  Thanks

Even more important is to write the rules in Visual Studio (old FXCop) that enforce these coding standards.  And to set many of these coding standards up in Visual Studio (Tools --> Options). Then as you write code - some are done automatically, others you are reminded of it.  

keith

December 31. 2008 16:13

Speednet

Very nice document!  I use most of your standards myself (already).  It's wonderful to see your name composition standards, such as Adjective(s) + Noun + Qualifier(s) for Enums.

There is one big area I hope you'll add to your document, and I have a couple of small points.

The "big" thing is comments and documentation.  I personally feel it is *essential* to document all code with the Microsoft XML-style comments before each and every object and function that is defined in the code.  You can literally document almost everything, and the more you document, the better it is all-around.

For example, I have found it immensely useful to document certain Enums, placing a <summary /> comment before each value within the Enum (if their purpose is not already simple and crystal clear).  Not only does that help with maintenance of the code, but it provides IntelliSense and speeds development, because you don't have to hunt down documentation of individual values.

Commenting methods/subs/functions with <param /> elements for each argument is similarly helpful.  There are many more examples.

On another subject, I think the one area that VB and C# need to diverge is is naming standards for private members.

I have noticed that many people use your syntax in C# for private members that store the values for public properties.  They use Pascal case for the property name and an identical name for the private member, but with camelCase.  C# uses case-sensitive names, so that method works well.

In VB, however, that is not the case, and if you use the same naming standard, you are forced to use the "Me." prefix before referencing the private member.  That is not ideal.

So in VB, I have found the best naming convention for the private member is to simply prepend an underscore character to the property name, and keep as Pascal case.  (For example, the value for the public property "FirstName" would be stored in the private member "_FirstName".)  Doing so instantly identifies that a particular name is a private member storing the value of a public property.  The code becomes instantly clearer, because these types of private members are special.

One additional area I would like to see defined in greater depth is that of attributes.  I personally think that attributes should always appear on their own line, one to a line.  For example, your Enumeration example (6.5) should appear as follows:

<Flags()> _
Public Enum PurchaseMethod
...

That's all for now; I just wanted to add a few things that stood out in my mind, but in no way does it diminish the fantastic work you did.  Thank you very much for sharing the fruits of your labor.

-Todd ("Speednet")

Speednet

December 31. 2008 16:28

trackback

Trackback from VistaDB .NET database blog

Free coding standards documents (VB.NET and C#)

VistaDB .NET database blog

December 31. 2008 16:40

Vijay

There will be some disagreement over any coding practice Smile
Thanks for the document. It was useful.

Vijay

December 31. 2008 17:47

trackback

Trackback from DotNetKicks.com

Holiday Goodie Bag: Free C# and VB Coding Standards Reference Document

DotNetKicks.com

December 31. 2008 18:48

Brett Mitchell

Thanks for the coding standards Clint.  I am in the middle of assembling the same type of document for Bisk.  I have been using my own personal preferences, the book Code Complete V2 and the teams input to create a WIKI that details out our standards.  And you’re right - we have had some pretty intense debates over the do’s and don’ts of various coding techniques.   The underscore being a very big one.  Smile

Brett Mitchell

December 31. 2008 19:12

nathan prather

Nice!

Thanks,
Nathan

nathan prather

December 31. 2008 19:12

Rachida Dukes

Thanks for sharing your knowledge, Happy Holidays.
Rachida

Rachida Dukes

December 31. 2008 19:29

Fuji

Cam on

Fuji

December 31. 2008 20:12

Eduardo Costa

Hi.

Good job! I have the same "role" here in my company. Is always complicated to agree about the code standards but they're really needed.

I'll share your post with my friends and co-workers.

Best regards.

Eduardo Costa

January 1. 2009 01:03

Zahid Rasool

thanks
great document

Zahid Rasool

January 1. 2009 02:13

Amgad Suliman

Thank you for sharing the document. Merry Christmas.

Amgad Suliman

January 1. 2009 02:50

bullpit

Thank you very much.

bullpit

January 1. 2009 08:37

Dale

Thanks for the documents.  They're well formatted and contain some good information.  But the emphasis on comments rather than on self-describing code should be changed.  Comments are a bad smell in a method and usually indicate the need to extract a new method.  Also, recommending foreach is probably not too good either.  Microsoft confesses that foreach is 3 to 5 times slower than for.

StringBuilder performs worse than concatenation when there are less than 5 iterations or concatenations.

The exceptions portion is good but if you can comment about an exception that might be thrown then you could have tested for that exception and not thrown the exception at all - except in the case of a class library where your exception is about parameters to your own methods.  Just pass the framework exception where one exists.

Ok, I know I have too much time on my hands. LOL

Dale

January 1. 2009 13:42

Vishal Khanna

Good work. This can be easily in Microsoft Source Analysis Tool... so that developers are get set go!

Vishal

Vishal Khanna

January 1. 2009 14:42

Brad

Thank you, i know my boss will be very happy to see this. Well written.

Brad

January 1. 2009 14:55

MJ Hufford

Many thanks!  Merry Christmas!

MJ Hufford

January 2. 2009 04:25

Talib Ali Khan

Excellent  work.....  

Please  keep  up  the  good work...

Talib Ali Khan

January 2. 2009 04:51

Ario

a million thanks...keep working ......... with the best wishes & Merry Christmas from Iran

Ario

January 2. 2009 13:26

trackback

Trackback from Rohland's blog

Coding Standards (C# and VB)

Rohland's blog

January 3. 2009 01:24

Ahamed aslam

very usefull document...thnx for sharing with us

Ahamed aslam

January 3. 2009 02:18

Ali

Great gift. Thanks man.

What about the "with" keyword. I know it is more of best practice than coding standard, but it makes the code neater and simplifies copy-and-past if needed.

Ali

January 3. 2009 08:19

Dre767

@ Dale

You may be right, but I think it would be a completely different document if it were geared toward performance, these standards seem to be geared toward clarity.

Dre767

January 3. 2009 11:59

dg

I disagree with this:

"o  Write the comments first. When writing a new method, write the comments for each step the method will perform before coding a single statement. These comments will become the headings for each block of code that gets implemented."

When written well, code should be self documenting.  Much of the literature on refactoring and attempts to get this message across. For example, if you find yourself writing a comment for a particular section/step of code, why not refactor that code into its own method with an intention-revealing method name?

Code documentation tends to add noise to code and cannot ever be relied on for accuracy.

dg

January 3. 2009 12:28

AGShoro

Good workd dear thanx

AGShoro

January 3. 2009 13:26

Yogesh

Thanks for providing good standards for coading....

Yogesh

January 3. 2009 13:42

pingback

Pingback from pandarion.wordpress.com

Coding Standard « Panda on Writing Tong

pandarion.wordpress.com

January 3. 2009 15:03

.NET Programmer

Thanks for sharing your documents.
I wish to see a code standardization document for T-SQL also Smile of course if you have one.

Great value, thanks
Eralper

.NET Programmer

January 3. 2009 15:37

PaddyLand74

Nice to follow these standards. Make you a better programmer.

PaddyLand74

January 3. 2009 16:36

Tosh

Clint,

StyleCop is a Microsoft Source Analysis tool that has coding standards that it checks.   http://blogs.msdn.com/sourceanalysis/
How well do these standards match up with those of StyleCop?

Tosh

January 3. 2009 16:41

Betawiz

I hate to ask this question. But Who is going to enforce these standards on a team? I think automated coding standards validation with reference is always helpful. Did you try StyleCop - code.msdn.microsoft.com/.../ProjectReleases.aspx

I would suggest to help the StyleCop team to improve the StyleCop instead of creating these type of documents.

Betawiz

January 3. 2009 17:00

Imran Buch

Shouldn't the Constants be named using upper case letters? Please share your thoughts?

Imran Buch

January 3. 2009 18:35

Clint Edmonson

Thank you to everyone for the great response to this post! Since I'm no longer working full time on a development team, these documents were collecting dust on my hard drive. They predate StyleCop and I have not verified them against the default settings in the tool.

StyleCop is definitely a good tool to add to your team's build process. Due to the general and broad nature of the standards a development team may devise, I would estimate that an automated tool could verify upwards of 80% of the rules that a team will agree upon.

Clint Edmonson

January 3. 2009 18:38

pingback

Pingback from freddes.se

Nice coding standard documents for C# (and VB.NET) at freddes.se

freddes.se

January 3. 2009 19:08

pei

It's very useful for me,
thanks a lot

pei

January 3. 2009 19:10

pingback

Pingback from marcelopetersen.com

Padrões de código em C# e VB.NET | Marcelo Petersen

marcelopetersen.com

January 3. 2009 19:18

teoman

It is gonna be useful. Thanks for sharing!

teoman

January 3. 2009 21:05

Colin Wood

Good job, needed and thanks

Colin Wood

January 7. 2009 03:02

Manish Parmar

Thanks,
This work is very useful for me,
I am very thankfull to u.

Manish Parmar

January 10. 2009 22:28

pingback

Pingback from dotnet-blog.com

.NET BLOG | Coding Standards Reference Document

dotnet-blog.com

January 11. 2009 17:06

iamac0der

Great Christmas present! Thanks Clint.

It's surprising how may software-shops out there don't even have a basic coding standards reference... this is a good starting point for them.

iamac0der

January 15. 2009 10:11

Harry

Thanks a lot~!!!!

It is a useful..^^;;

Harry

January 17. 2009 02:24

Jürgen Ebner

Thanks for your comment to my Blog entry.

I think it was an interessting und very useful entry so I have link your post to my link.

Cheers
Jürgen

Jürgen Ebner

January 17. 2009 08:42

pingback

Pingback from smehrozalam.wordpress.com

C# Coding Standards « Mehroz’s Experiments

smehrozalam.wordpress.com

January 17. 2009 20:32

pingback

Pingback from fiquepordentro.net

Fique por dentro Nomenclatura  » Blog Archive   » Holiday Goodie Bag: Free C# and VB Coding Standards Reference …

fiquepordentro.net

January 25. 2009 18:40

Higor Ramos

Hello guy, I made some additions to your code standard and I'm distributing it ok? I will put your blog address. Thanks for the great document that you made.

Higor Ramos

February 7. 2009 08:35

trackback

Trackback from No1 Microsoft Fan

Eric Nelson on Free Software and how to get it

No1 Microsoft Fan

March 10. 2009 09:48

pingback

Pingback from batuhanbulak.com

C# Vb.Net Coding Standart | Batuhan Bulak

batuhanbulak.com

March 28. 2009 22:53

Daniel Gimenez

Love the doc.  Wish you could provide a full example C# class demonstrating everything.  Probably easier to give devs something they can reference.

Daniel Gimenez

April 16. 2009 05:34

J. Williams

Great style guide.
You may find the free Atomineer Utils add-in useful for the documentation comment part of your style, as it can enforce a strict style on DocXml comments, automatically builds meaningful and descriptive comments for most code elements, and even documents exceptions thrown by the method, so it takes all the pain out of keeping the documentation tidy and in sync with the actual code - It will update existing comments to reflect any changes in the code as well as creating new ones.

http://www.atomineer.com/AtomineerUtils.html

J. Williams

May 25. 2009 22:01

Sikis

thank you for

Sikis

June 16. 2009 08:48

Mike

Thanks for posting this!  It gives my group a great document to start from.

Mike

June 17. 2009 10:02

pingback

Pingback from unidevtech.com

Coding Standards and SQL Mistakes | Unidev .NET Technology Blog

unidevtech.com

June 20. 2009 11:47

Dale

Great guide.

For my employer, I'd add something about deployment standards (ie. thou shall not require Admin privileges or write into System32) and avoiding banned function calls (ie. thou shall not use function calls on the SDL banned list).

Ref: blogs.msdn.com/.../...hygiene-and-banned-apis.aspx

Dale

June 30. 2009 15:35

Sumit Joshi

Great Job Done Yaaarrrr...

You really did great job. I also love to code with standards. I have studied so many standards. But what I was
following is the same as you have. You did nice work.

Live Long....yaaaaarrrrr........

Sumit Joshi
joshisumitcomp@yahoo.co.in

Sumit Joshi

June 30. 2009 17:21

Sumit Joshi

Great work dont yaaaarrrr...
You gave conding standard from ground and with so much clarity.
Really, I loved it. I will also share this with my company also.
I had seen so many standards but liked your documentations better.

I love to work with stardards but they should be lovable so that it
can give us pleasure...

You did the same....
Again thanks...yaaaarrr.....

Sumit Joshi
joshisumitcomp@yahoo.co.in

Sumit Joshi

July 1. 2009 12:02

Dilli

Thanxs dude

Dilli

August 29. 2009 04:48

pingback

Pingback from topsy.com

Twitter Trackbacks for
        
        Holiday Goodie Bag: Free C# and VB Coding Standards Reference Documents
        [notsotrivial.net]
        on Topsy.com

topsy.com

October 3. 2009 04:57

pingback

Pingback from rohland.co.za

Rohland's Blog  » Blog Archive   » Coding Standards (C# and VB)

rohland.co.za

April 20. 2011 19:35

pingback

Pingback from watchtvonmypc.org

traffic travis 4 bonus

watchtvonmypc.org