VB.NET Coding Standards

[Raven65]

Hey guys, we're looking to lay out some group and corporate level coding standars at my current workplace.

We're basically an exclusivly VB.NET shop, so the rule set will be modified specifically with that in mind.

I'm browsing around now and have found some good "base line" lists of suggestions in addition to those provided my Microsoft, but wanted to see if you in the community had any input.

Does anyone have any "on the job" suggestions for situtations you've come up against, or perhaps excerpts from your groups standards guidelines?

 

[cjard]

Turn Option Strict On
Remove the Microsoft.VisualBasic.dll reference
Use .NET-wide functions, constants etc (MessageBox.Show vs MsgBox, Envoironemnt.NewLine vs vbNewLine)
Dont use With/EndWith
Make them aware that IsNot is available (If myVar IsNot Nothing vs If Not myVar Is Nothing)
Use Modules sparingly
Dim your variables when you need them, not at the top of the procedure
Avoid code blocks longer than one page (7 page If Else blocks for example)
Never leave a Catch block blank
Do not use "old" VB like "Call MyFunction"
Put empty brackets on the end of function calls (Dim s As String = myObj.ToString() )
Use Enums for constants if appropriate
Prefer collections over arrays where growth is required
Prefer typed generic(Of T) collections if available
Do data access the typed way (MyDataSet.MyDataTable(0).MyColumn.Value vs MyDataSet.Tables("MyDataTable").Rows.Item(0).Item("MyColumn").Value.ToString())
Use meaningful comments (see http://www.codeguru.com/cpp/misc/samples/testingdebugging/article.php/c12815/)
Make code self documenting to reduce the need for comments
Drink plenty of water, eat well and dont play on the computer too much

 

[vis781]

Some good stuff there but if you want to know if you are conforming to set standards check out FXCop in my sig and run it against an app you have written. Don't panic if you get a couple of hundred things crop up though.

 

[Raven65]

Awesome, thanks for the input. I'm hoping to have a draft of this thing soon, I'll upload it if your interested in commenting further. A few points I wondered if you would expand on though, just so I have a supporting statment for why its important in the document.

Why do you have these:

Remove the Microsoft.VisualBasic.dll reference
Dont use With/EndWith

 

[JohnH]

With/EndWith may obscure code readability in longer (than a few lines) code blocks.

 

[cjard]

Remove the Microsoft.VisualBasic.dll reference
Dont use With/EndWith

MS.VB.dll provides syntactical compatibility with legacy VB applications. In most cases there are better, modern, .NET ways of doing the same things that are usable across all .NET syntaxes. It's mainly an issue of code conformity.
For example, MessageBox.Show() is the .NET way of showing a messagebox. MS.VB.dll has a wrapper function called MsgBox() for a variety of reasons, most notably the ability to paste/migrate VB6 code into VB.NET and also as a soft-option of VB6 developers who are upgrading their knowledge.
Like most legacy compatibility offerings it ultimately holds you back because it gives your programs a VB-only skew. Any route in life that includes some kind of progress necessarily has a moment when the old is left behind.
If you ensure that your app is written in .NET pure ways then it enhances the ability of your developers to read other .NET syntaxes, and additionally enables other syntax developers to read the code. While not the only benefits, your guys could more easily crosstrain to C# if there was a sudden need, or a hired in C# developer would have a better chance of reading the VB


With/EndWith are a shortcutting notion that I've never partcularly gotten on with. Its possible to have With blocks nested inside each other to the extent that you could degenerate an entire page of code into a set of nested Withs, and objectless property/method calls. If you need to shortcut a reference, there is nothing preventing the use of the more readable option of dimming a typed variable to the shortcut you wish to take.

i.e. instead of
With ListView1.Items
' blah
.SubItems(1) ...
.This
.That
.Other
End With

you can:
Dim lic as ListViewItemCollection = ListView1.Items
lic.SubItems
lic.This
lic.That
lic.Other


Its little extra typing for a lot more readability

 

[Raven65]

Excellent explainations for both! Thanks so much for your time thus far, might have a few more questions as I go along.

 

[Administrator]

Microsoft's Naming Guidelines may also be of interest.

 

[Raven65]

Microsoft's Naming Guidelines may also be of interest.

Yea, those are the basis for topics 1-3 in my doc so far (naming variables, methods, and classes).

Looking for any more that any one has to offer, and especially stuff like cjard has mentioned above with perhaps "less known" good practices.

I'm basically having to compile a standards document that also will teach many of our current developers HOW to do the new standards...something of a cross between Best Practices and a tutorial. =\

 

[bmilano]

My two cents

I've been in software development for 19+ years, but only been doing VB .NET for 2+, so most of what I have to add is not VB-specific. Also, some of these are very much my opinion, so take them as such:

1. Decide on a standard for marking changes in previously released code.

2. Always comment out old code and put new code in in previously released code. Never change the code in place.

3. Regarding marking additions/changes/deletions in the code, remove all such marks and all code BEFORE starting the next full release. For most of my career, I operated in groups where the most recent set of changes would remain in the code, and only prior ones would be cleaned up. I've now come to believe (and am currently operating as such) that a new release should start clean.

4. Related to the previous post, do NOT spend a lot of effort explaining the change itself in the modification log. The modification log will eventually go away. Make your explanations of what's going on in the regular comments, which will stick around indefinitely.

5. For any sort of catastrophic condition being trapped, put a unique error code in any messages displayed to the user and/or written to a log. Never, ever use a particular code in more than one place in the program. That way, when getting problem reports from the field, you will know EXACTLY where the error is in the code. This will necessitate keeping some sort of master list for all these codes that all the developers can update.

6. Never use hardcoded values within your procedure code. When you are dealing with maximum amounts, strings used to retrieve application configuration parameters, etc., they should be defined as Const variables. That will make them easier to find and prevent mistakes if they are used in multiple places.

Bill

 

[Administrator]

This is another scenario (related to another thread I posted) where I would love to see a method for us to collaborate on a document such as this. If we as a community could share in the development of something as "simple" as VB.NET coding standards, I think we could all benefit from it. Sure, some things would change per employer/workplace, but the gist of the document (a core) would benefit us all. I'm open to suggestions on how to offer such a collaboration system for us to work with.

 

[TechGnome]

2. Always comment out old code and put new code in in previously released code. Never change the code in place.

I don't necessarily agree with this... especialy with the next recommendation...

3. Regarding marking additions/changes/deletions in the code, remove all such marks and all code BEFORE starting the next full release. For most of my career, I operated in groups where the most recent set of changes would remain in the code, and only prior ones would be cleaned up. I've now come to believe (and am currently operating as such) that a new release should start clean.

While I agree that released code bases should be clean, what's the point of marking changes if they are all going to be removed? If you are looking for tracks in the sand, then 1) The code is not the place to track changes, 2) Maybe source code control is needed, 3) There should be documentation (GASP! Did I just say the "D" word?) for that change in the first place.

4. Related to the previous post, do NOT spend a lot of effort explaining the change itself in the modification log. The modification log will eventually go away. Make your explanations of what's going on in the regular comments, which will stick around indefinitely.

Again, if it's going to go away, then it shouldn't be there.... You're creating work for the sake of documentation that isn't adding any value.

But these too are just my opin, and I well aware of it's value here.

cjard - RE: nested Withs.... EEEWWW.... that's when you create a standard that with statements only go one level.... but then again, I haven't come across a "need" to use it in .NET.


We are also going through the samething in our shop....
Something that hasn't been mentioned yet: Turn OPTION EXPLICIT ON.... I know it's on by default, but it should still be mentioned as part of the standard.

Some of the things we've comeup with have also been a lot more mundane stuff.... casing (using Camel Case vs Pascal Case - whose definitions it seems I've had reversed all the years ) ... Making sure that all methods/subs/functions are atomic. Meaning that they do one thing and one thing only.... even if that one thing is to call 12 other functions.... We've got code that is all over the place in what it does and makes it hard to isolate problems.

With a few exceptions (and it's primarily related to our setup & architecture here), I think cjard's list is spot on.

However, the biggest key to this is going to be consistency. You and your developers have got to all agree on the standards, and stick to them.... and be ruthless about it. Don't give them an inch.... once you open a crack for "jsut this one time"..... you'll be amazed at how many "just this one time" you end up with.

-tg

 

[bmilano]

I hear ya'...

Techgnome,

I hear ya'...like I said, it's personal opinion. I realize that my belief in cleaning the stuff out may be unpopular, but I was looking at it in the context that:

1. That code was still available for everyone to look at. e.g. you release 3.0, and you clean out all the change markings before starting 3.1. Everyone still has a frozen 3.0 set of source code available with all the marked changes.
2. Since 3.0 was (in theory) fully tested before it went out the door, you should (in theory) have working code to start from for 3.1, so having the prior versions always in your face isn't really necessary.

Also, I'm generally a neat freak and I hate clutter. So that may have something to do with my personal bias.

Bill

 

[p_nivalis]

Use Modules sparingly
Dim your variables when you need them, not at the top of the procedure
Do not use "old" VB like "Call MyFunction"

As an old vb6 dev and learning the vb.net ropes, can you expand on the reasons for the above 3 rules?

I was always told that any time you can keep the main form code "light", and when certain functions may be reusable, it's best to throw them into a module, so that you can always just add the module to any other program as needed, rather than go back and rip the code from the form(s).

For dimming vars in a procedure, I was told that it's best to always declare all of them at the top, so that they will be much easier to find should a problem arise, rather than having them scattered through, possible very large code blocks.

And I was also always told using "Call" before calling a function, also makes it easier to quickly understand code at a glance, because you can easily see that there is a call being made to a possibly oddly named function.

thanks

 

[JohnH]

.Net is geared towards object oriented programming, reuse(ability) is important but mostly in the context of classes. Classes are object-oriented, but modules are not. You won't find much modules in the .Net framework library, instead Shared methods are added to appropriate classes.

A variable is usually declared and assigned a value in one statement. That's one line of code instead of two, and makes programming easier and more readable, you don't have to jump back and forth that much when writing or reading. This is also related to strong typing of variables which is much more emphasized in .Net than classic VB. Also, large code blocks in a single method is a no-no, break it down, think OOP.

Call statement is actually encouraged in documentation for readability. Personally I've never used it, not even in classic VB where it was very common coding "style". This is just laziness by my call and I should probably use it.