Codified Coding Standards (VB.NET/C#.NET (1.0/1.1/2.0))

Topic

New Reply

Has anyone come across a good document for VB.NET or C#.NET Coding Standards?

I’m curious because some of my colleagues developed custom coding standards for use within our company. Many of their ideas came from a number of external sources as well as their own experience. These documents cover things like object naming conventions, inline commenting requirements, etc.

One of the interesting things that we’ve implemented is the removal of any and all Hungarian notation. The biggest reason is that the IDE can provide the object type and scope with a quick mouse-over so prefixes are no longer needed. Instead, we try to name all objects (variables, classes, text boxes, etc) with good, descriptive names. For instance, strOrdDesc would become orderDescription. Also, we’ve done away with abbreviations. It was difficult for me to make the switch (old habits die hard), but now that I’ve done it I’m VERY glad! My code has never been cleaner, more readable, and more efficient!

Since we are mostly a VB shop at the moment, I have not ventured out into C# standards territory much. Although I have come across one document, in particular, that looks very well written: http://home.comcast.net/~lancehunt/CSharp_…g_Standards.pdf%5B/url%5D, by Lance Hunt.

Does anyone else have any thoughts or documents to share on this subject?

Reply | Quote

Replies

Just thoughts. I’m aware that Microsoft is recommending dropping Hungarian notation for naming objects. I think some of the push for this is coming from people who have always objected to being forced to use a naming convention, and Microsoft, in spite of the lip service they’ve paid to Hungarian, has never really bought into it. The belief that there are just too many objects for a realistic naming convention is nonsense IMHO. You don’t use all those objects at once, and it is still easier to read code where you know that a string object will be named strSomething without having to hover a mouse over it in code to tell what it is.

Proponents of no Hungarian seem to ignore the fact that when you have a large product, you sometimes lose objects in the forest. We still use Hungarian for variables within our code and for naming controls on forms, webforms and reports. I am lobbying for their use on form and report objects as well, since we can all see that it is much easier to sort out reports from menus from subreports from forms in the same assembly when a naming convention is applied. Otherwise, you have to look at the file extension, and that may not be enough if you’re dealing with a web application. For instance, with an object named DailyReport.aspx and another named DailyReport.rpx, wouldn’t it be less confusing to use tags like rptDailyReport.rpx? It’s much easier to identify mnuDailyReport.aspx as a menu page in a web app when you’re wading through the objects. If you have dozens or hundreds of forms or reports, why make it hard on yourself? Our apps are complex and all the forms or all the reports won’t be in separate assemblies, so why make it harder on ourselves?

Reply | Quote

Charlotte,

I agree with your thoughts regarding object naming in large applications and I don’t have an argument against it. But let me share a revelation I had regarding object names while working on one of my first projects without using prefixes.

I was creating a simple web form that had multiple panels – one panel for Viewing and one for Editing certain fields. Previously, I would name the objects something like cboState (in the edit panel) and lblState (in the View panel). This was nice because all of the objects were sorted by type in the Class Name drop down (at the top-left of the Code window). I could easily find all of the drop downs, labels, text boxes, etc.

When I implemented the new naming conventions I used the following names for the corresponding objects: editStateDropDown and viewStateLabel. (Note: I don’t always include the object type in the name, but sometimes it’s helpful.) What I discovered is that the objects sorted by their function rather than object-type. This was MUCH more helpful to me while coding, especially when making use of the intellisense. All I have to do is start typing the role of the object (“edit…”) to get the intellisense. Talk about saving time and making much more readable code!

I realize that the benefits of this technique are not quite so overwhelming when you’re working with dozens of web page (aspx) and user control (ascx) files. I guess the icons in the Solution Explorer window are too small to make the case for identifying the object with its icon…

Reply | Quote

I can see your point, but it doesn’t necessarily apply to the kind of things we’re doing. We’re creating .Net versions of existing Access forms and reports and designing the next generation product as we go, plus finishing a web application that interfaces the Access app data. It makes it a great deal easier to make that transition if we use the same naming for stuff that translates directly. Otherwise, we wind up with the same ugly default names MS used to wish on us in Access, and what’s the point in that? Comparing behavior and translating code is far easier when we can be sure we’re comparing Apples.Net to Apples.Access. In our Windows apps, we group form, reports, etc. into folders, but it is still alot easier to keep them straight when we know what they are from their names.

Reply | Quote

I can see your point, but it doesn’t necessarily apply to the kind of things we’re doing. We’re creating .Net versions of existing Access forms and reports and designing the next generation product as we go, plus finishing a web application that interfaces the Access app data. It makes it a great deal easier to make that transition if we use the same naming for stuff that translates directly. Otherwise, we wind up with the same ugly default names MS used to wish on us in Access, and what’s the point in that? Comparing behavior and translating code is far easier when we can be sure we’re comparing Apples.Net to Apples.Access. In our Windows apps, we group form, reports, etc. into folders, but it is still alot easier to keep them straight when we know what they are from their names.

Reply | Quote

Charlotte,

I agree with your thoughts regarding object naming in large applications and I don’t have an argument against it. But let me share a revelation I had regarding object names while working on one of my first projects without using prefixes.

I was creating a simple web form that had multiple panels – one panel for Viewing and one for Editing certain fields. Previously, I would name the objects something like cboState (in the edit panel) and lblState (in the View panel). This was nice because all of the objects were sorted by type in the Class Name drop down (at the top-left of the Code window). I could easily find all of the drop downs, labels, text boxes, etc.

When I implemented the new naming conventions I used the following names for the corresponding objects: editStateDropDown and viewStateLabel. (Note: I don’t always include the object type in the name, but sometimes it’s helpful.) What I discovered is that the objects sorted by their function rather than object-type. This was MUCH more helpful to me while coding, especially when making use of the intellisense. All I have to do is start typing the role of the object (“edit…”) to get the intellisense. Talk about saving time and making much more readable code!

I realize that the benefits of this technique are not quite so overwhelming when you’re working with dozens of web page (aspx) and user control (ascx) files. I guess the icons in the Solution Explorer window are too small to make the case for identifying the object with its icon…

Reply | Quote

I must agree with Charlotte.

MSFT is overhyping that the .NET IDE reducues the need for type naming converntions.

To the contrary.

Too many flokes who call themselves programmers rarely, if ever, “desk check” code by printing and examining code off line.
If they, or others, need to look at program listings that do not use well defined type naming conventions, good luck!

MSFT is just encouragging such bad behavior.

Heck, this ain’t worth discussing.

Reply | Quote

Ooops, I forgot to mention that there are cases in which “typeless” names can be useful.
For example, see the code in the .zip file linked to http://www.standards.com/Sorting/SortPerfo…rison-Info.html%5B/url%5D.

Reply | Quote

Ooops, I forgot to mention that there are cases in which “typeless” names can be useful.
For example, see the code in the .zip file linked to http://www.standards.com/Sorting/SortPerfo…rison-Info.html%5B/url%5D.

Reply | Quote

> Heck, this ain’t worth discussing.

When I have this revelation, I usually use the Back button instead of the Post It button.

But anyway, I disagree with you. As long as all the developers are on the same page, and so is the client, why follow old rules?

I guess you won’t reply because this isn’t worth discussing.

Reply | Quote

I’ll take the liberty of answering, Jefferson. Is itsn’t a case of “following old rules”, it’s a matter of *applying* rules so that other developers can easily pick up and carry the work forward. Anything that facilitates that is a good idea. Anything that makes the learning curve even steeper, isn’t. The problems may not arise right now, when everyone has agreed to do it a particular way. They turn up when all those people leave an are replaced by others who have to figure out what the blazes their predecessors thought they were doing! I have been in that position often enough to prefer to stick with an approach that makes it simpler for anyone else following behind me to decipher my code and my rationale with the least amount of mental effort. It isn’t a test, after all, it’s a matter of productivity.

Reply | Quote

I’ll take the liberty of answering, Jefferson. Is itsn’t a case of “following old rules”, it’s a matter of *applying* rules so that other developers can easily pick up and carry the work forward. Anything that facilitates that is a good idea. Anything that makes the learning curve even steeper, isn’t. The problems may not arise right now, when everyone has agreed to do it a particular way. They turn up when all those people leave an are replaced by others who have to figure out what the blazes their predecessors thought they were doing! I have been in that position often enough to prefer to stick with an approach that makes it simpler for anyone else following behind me to decipher my code and my rationale with the least amount of mental effort. It isn’t a test, after all, it’s a matter of productivity.

Reply | Quote

> Heck, this ain’t worth discussing.

When I have this revelation, I usually use the Back button instead of the Post It button.

But anyway, I disagree with you. As long as all the developers are on the same page, and so is the client, why follow old rules?

I guess you won’t reply because this isn’t worth discussing.

Reply | Quote

I must agree with Charlotte.

MSFT is overhyping that the .NET IDE reducues the need for type naming converntions.

To the contrary.

Too many flokes who call themselves programmers rarely, if ever, “desk check” code by printing and examining code off line.
If they, or others, need to look at program listings that do not use well defined type naming conventions, good luck!

MSFT is just encouragging such bad behavior.

Heck, this ain’t worth discussing.

Reply | Quote

Don’t forget that Microsoft are the people that also in most of their examples prefix ALL variables with ‘my’ (myDataAdapter, myString, myObject).

I ask you is that a good example to be setting? and more to the point? Is that someone we should be listening to for advice about nomenclature?

Reply | Quote

Unfortunately, they have enshrined MyBase in .Net, so we’re stuck with it.

Reply | Quote

Unfortunately, they have enshrined MyBase in .Net, so we’re stuck with it.

Reply | Quote

Don’t forget that Microsoft are the people that also in most of their examples prefix ALL variables with ‘my’ (myDataAdapter, myString, myObject).

I ask you is that a good example to be setting? and more to the point? Is that someone we should be listening to for advice about nomenclature?

Reply | Quote

I enforce Hungarian notation rigidly, in fact our external IT auditors have made compliance part of the companies requirements.

In my opinion not only does it enable programmers who are not the author of the code to see at a glance what type the variable is it makes the programmer think about the code he is producing.

As for a good document for coding standards, good luck. if you ask 5 developers what their coding standards are you’ll get 6 different answers.

Regards,
Kevin Belll

Reply | Quote

I enforce Hungarian notation rigidly, in fact our external IT auditors have made compliance part of the companies requirements.

In my opinion not only does it enable programmers who are not the author of the code to see at a glance what type the variable is it makes the programmer think about the code he is producing.

As for a good document for coding standards, good luck. if you ask 5 developers what their coding standards are you’ll get 6 different answers.

Regards,
Kevin Belll

Reply | Quote

I have a book (Microsoft Press) on Coding Standards for .NET at work, I will post it’s details tomorrow. I found it a good foundation and discussion more than anything, and it helped me put some things straight in my own mind.

I guess the largest departure (or rather recommended departure) from VB6 to .NET with regard to coding standards I have struggled to work out the ‘right’ answer for is that of notation of variables. Interestingly the Microsoft Press book endorses Hungarian notation for .NET and briefly discusses it.

After much thought, some discussion with fellow developers and some reading, I have come to the conclusion that using Hungarian notation is a better idea than not. Basically, when I am reading through code (note: I do mean reading and not ‘stepping’) i don’t want to have to hover over ever variable to work out what it’s data type is…this is slow and counter-intuative. VB6 has not much of a different feature where we could have done away with Hungarian notation on the same grounds, simply by pressing SHIFT-F2 and SHIFT-ALT-F2 … but we didn’t do this and do away with Hungarian notation… ? Why … because it doesn’t help with ‘reading’ code.

At the end of the day, a standard is a standard. I guess that there are good and bad things bout using or not using Hungarian notation. To me, the MOST important issue is that your company or team has a standard , it is well defined, everyone sticks to it (unless there is a good reason not too) and the standard is DOCUMENTED.

Reply | Quote

I have a book (Microsoft Press) on Coding Standards for .NET at work, I will post it’s details tomorrow. I found it a good foundation and discussion more than anything, and it helped me put some things straight in my own mind.

I guess the largest departure (or rather recommended departure) from VB6 to .NET with regard to coding standards I have struggled to work out the ‘right’ answer for is that of notation of variables. Interestingly the Microsoft Press book endorses Hungarian notation for .NET and briefly discusses it.

After much thought, some discussion with fellow developers and some reading, I have come to the conclusion that using Hungarian notation is a better idea than not. Basically, when I am reading through code (note: I do mean reading and not ‘stepping’) i don’t want to have to hover over ever variable to work out what it’s data type is…this is slow and counter-intuative. VB6 has not much of a different feature where we could have done away with Hungarian notation on the same grounds, simply by pressing SHIFT-F2 and SHIFT-ALT-F2 … but we didn’t do this and do away with Hungarian notation… ? Why … because it doesn’t help with ‘reading’ code.

At the end of the day, a standard is a standard. I guess that there are good and bad things bout using or not using Hungarian notation. To me, the MOST important issue is that your company or team has a standard , it is well defined, everyone sticks to it (unless there is a good reason not too) and the standard is DOCUMENTED.

Reply | Quote

To follow on from my last post, but on a slightly different tangent (hence the seperate post), I am using Hungarian notation and we have enshrined that in coding standards at my workplace. However, we have opted to use standard hungarian notation for ‘common’ variables and controls, ie such as string, integer, long, byte, textbox, combobox etc. We have drawn a line in the sand though, and only use the Prefix of ‘obj’ for the plethora of other not-so-common variables and objects, ie. DataReaders, DataAdapters etc.

The rationale behind this is that the not-so-common occurence of these objects means that we can use the description of the object type as part of the name, with an adjective to describe seperate functions of the same variable within a procedure…

objDataAdapter
objDataReader

or

objDataReaderPatient
objDataReaderEpisode

The only dilemma that I have had is to work out how to differentiate a truely OBJECT data type … if in fact I need to?

What this means is that the hungarian notation ‘dictionary’ if you like is small enough to not have to worry about continually referencing obscure data types or objects in documentation, which in .net, due to it’s rich object model, could be onerous, but to focus on making the code readable and understandable at a glance.

Reply | Quote

To follow on from my last post, but on a slightly different tangent (hence the seperate post), I am using Hungarian notation and we have enshrined that in coding standards at my workplace. However, we have opted to use standard hungarian notation for ‘common’ variables and controls, ie such as string, integer, long, byte, textbox, combobox etc. We have drawn a line in the sand though, and only use the Prefix of ‘obj’ for the plethora of other not-so-common variables and objects, ie. DataReaders, DataAdapters etc.

The rationale behind this is that the not-so-common occurence of these objects means that we can use the description of the object type as part of the name, with an adjective to describe seperate functions of the same variable within a procedure…

objDataAdapter
objDataReader

or

objDataReaderPatient
objDataReaderEpisode

The only dilemma that I have had is to work out how to differentiate a truely OBJECT data type … if in fact I need to?

What this means is that the hungarian notation ‘dictionary’ if you like is small enough to not have to worry about continually referencing obscure data types or objects in documentation, which in .net, due to it’s rich object model, could be onerous, but to focus on making the code readable and understandable at a glance.

Reply | Quote

I don’t disagree with your methods. The most important issue is standardization within an organization rather than global standardization among all developers.

The developers at my company faced the same argument regarding ‘common’ Hungarian prefixes. It turns out that the .NET framework provides such a large variety of object types (and EVERYTHING is an object – even variables) that we could not come up with enough unique prefixes that made sense.

For instance, how do you distinguish the difference between a Windows textbox and a Web textbox? Obviously, both would begin with “txt” but that seemes to have defeated the purpose of finding unique prefixes for each object type. Additionally, we had one developer who preferred prefixing buttons with “cmd” while others prefer “btn.”

This brings me back to a point in an earlier post – if objects (and variables, which are also objects) are named with good, descriptive names the type of the object will be somewhat self-evident based on its function. Granted, this concept may not be as applicable to certain types of developers, such as those who work with more math-based code. But I can say that this approach has worked very well with our team, where our coding is heavy on the database side.

I did not mean to turn this thread into a discussion over the use of prefixes. Rather, I was hoping to find out what kinds of standards documents other loungers were using (assuming they are non-sensitive and can be shared with others).

Reply | Quote

The book that I have found and thought was a good ‘introduction’ to the topic of coding standards in .NET is:

Practical Standards for Microsoft Visual Basic .NET , James Foxall, Microsoft Press.

It covers a good range of topics, including Design, Conventions, Coding Constructs (Formatting Code, Commenting Code, Looping Structures, Exception Handling), Advanced Programming, User Interface Designed, User Input and Notification, Version Control and Source Code control.

It is about 450 pages, so covers a reasonable amount. It isn’t close to being exhaustive, but is a good place to start I found when thinking about the topic.

Cheers

J

Reply | Quote

Thanks for the refefence, Jayden. I’ll check that out.

Reply | Quote

Thanks for the refefence, Jayden. I’ll check that out.

Reply | Quote

We have that book, but I have to disagree with his approach to naming conventions. It makes sense when creating object methods and properties, but when dealing with an interface, I want names that immediately indicate that an object is a form, report, etc. We struggling with variable naming right now, so stay tuned!

Reply | Quote

We have that book, but I have to disagree with his approach to naming conventions. It makes sense when creating object methods and properties, but when dealing with an interface, I want names that immediately indicate that an object is a form, report, etc. We struggling with variable naming right now, so stay tuned!

Reply | Quote

The book that I have found and thought was a good ‘introduction’ to the topic of coding standards in .NET is:

Practical Standards for Microsoft Visual Basic .NET , James Foxall, Microsoft Press.

It covers a good range of topics, including Design, Conventions, Coding Constructs (Formatting Code, Commenting Code, Looping Structures, Exception Handling), Advanced Programming, User Interface Designed, User Input and Notification, Version Control and Source Code control.

It is about 450 pages, so covers a reasonable amount. It isn’t close to being exhaustive, but is a good place to start I found when thinking about the topic.

Cheers

J

Reply | Quote

I don’t disagree with your methods. The most important issue is standardization within an organization rather than global standardization among all developers.

The developers at my company faced the same argument regarding ‘common’ Hungarian prefixes. It turns out that the .NET framework provides such a large variety of object types (and EVERYTHING is an object – even variables) that we could not come up with enough unique prefixes that made sense.

For instance, how do you distinguish the difference between a Windows textbox and a Web textbox? Obviously, both would begin with “txt” but that seemes to have defeated the purpose of finding unique prefixes for each object type. Additionally, we had one developer who preferred prefixing buttons with “cmd” while others prefer “btn.”

This brings me back to a point in an earlier post – if objects (and variables, which are also objects) are named with good, descriptive names the type of the object will be somewhat self-evident based on its function. Granted, this concept may not be as applicable to certain types of developers, such as those who work with more math-based code. But I can say that this approach has worked very well with our team, where our coding is heavy on the database side.

I did not mean to turn this thread into a discussion over the use of prefixes. Rather, I was hoping to find out what kinds of standards documents other loungers were using (assuming they are non-sensitive and can be shared with others).

Reply | Quote