Visual Basic. Net sample guidelines

Visualized basic 2002

Gotdotnet

Visual Basic. Net sample guidelines

These guidelines are used by Microsoft to develop samples and documentation. they are provided to Visual Basic. net users as a basis for their own coding standards. the Visual Basic language specification does not contain a coding standard.

The primary goals of the coding Convention are:

• Allow users to carry knowledge from one sample to another sample.
• Create a consistent look to the Code, so that readers can focus on the content, not layout.
• Make copying, changing, and maintaining the code easier.
• Provide a transition path from Visual Basic 6 to Visual Basic. net.
• Demonstrate Visual Basic. Net "Best practices ."

This document provides a concise set of guidelines that apply to Visual Basic. net sample applications distributed by Microsoft. it is not meant to be a discussion on software development and writing code. for information on developing coding standards, see the resources section.

Table of contents

1Coding Standard
1.1Names
1.1.1Ado. Net class variables
1.2Comments
1.3Format
2Do things the Visual Basic. Net way
3Design Guidelines
3.1General
3.2Projects and Solutions
 3.3Localization
3.4Accessibility
3.5Security
4Resources

1 coding standard

The coding standard is not an exhaustive list of How to Write quality code. Instead, it lays out a minimum standard that all code must meet.

1.1 Names

• Follow the naming guidelines in design guidelines for class library developers.
• The prefix m_Is allowed, but not required, on private and protected class fields.
• Do not use single-letter names, random t for I, j, and K for loop variables.
• Use ex As the local exception variable in a try again atch statement.
• Constants are named using Pascal casing (see design guidelines for class library developers ).
• Type prefixes are allowed, but not required, for Toolbox components (Objects dragged onto a designer from the Toolbox ).
• Keep it professional. Do not use offensive language, for example, "foo" and "bar ".

1.1.1 ADO. Net class variables

• Express the name of datatable variables in the plural form. For example, use employees rather than employee.
• Do not repeat the table name in the column name. If the datatable name is employee, LastName Is preferred over EmployeeLastName. The exception is for ID fields contained in multiple tables, so that EmployeesTable may contain EmployeeID Field.
• Do not induplicate ate the data type in the name of a column. If the data type is later changed, and the column name is not changed, the column name wocould be misleading. For example, LastName Is preferred over stringLastName.

1.2 comments

• Comment each type, each non-public type member, and each region declaration.
• Use end-line comments only on variable declaration lines. end-line comments are comments that follow code on a single line.
• Do not create formatted blocks of asterisks that surround comments.
• Separate comments from comment delimiters (apostrophe) with one space.
• Begin the comment text with an uppercase letter.
• End the comment with a period.
• If the comment starts with a verb, it shoshould Be In The Imperative (loop, add, write, and so forth ).
• Explain the Code; do not repeat it.

1.3 format

• Use the "Pretty listing" feature (in the Tools Options dialog box) of Visual Basic. net to format the code. use the default settings for the pretty listing feature (smart indenting, Tab 4, indent 4, insert spaces ).
• Indent continuation lines one tab stop.
• Write only one statement per line.
• Add at least one blank line between method and property definitions.
• Define only one type (class, Enum, interface, and so forth) in each file.

2 do things the Visual Basic. Net way

• Use Visual Basic runtime methods rather than. NET Framework objects.
• Use the short method for instantiating classes.

  ' Preferred. Dim Employees As New Collection() ' Not preferred. Dim Employees As Collection = New Collection()

• Do not explicitly instantiate a delegate inAddhandlerStatement.
• UseDeclareStatement rather thanDllimportAttribute to access native APIs.
• Avoid use of single-lineIfStatement.
• Declare the array length with the variable name.

  ' Preferred. Dim Buttons(4) As Button ' Not preferred. Dim Buttons() As Button = New Button() {}

• UseTry another atchRather than "on error ".
• UseHandlesClause ratherAddhandlerStatement.
• UseCSTR ()InsteadSTR ().
• UseCINT ()InsteadINT ().
• Use Option strict on, either as a project setting, or as a statement in each file.
• Use Option explicit on, either as a project setting, or as a statement in each file.
• Use the complete class name when applying an attribute.
• Use shared methods in classes rather than global methods in modules.
• Do not use type characters ($, %, and so on ).
• Do not useCall.

3 design guidelines

The design guidelines cover the more complex issues in creating a sample. They cover issues that are beyond one line of code.

3.1 General

• Follow the design guidelines in design guidelines for class library developers.
• Specify the prompt and title of msgbox CILS.

3.2 Projects and Solutions

• Put all code in a project or solution.
• Include in each solution a readme.htm file that includes des the title, features, requirements, and directions for running the application.
• Include setup projects in web forms and XML Web Service solutions.
• Delete the bin and OBJ directories before distributing a sample.
• Use the default encoding to save files.
• UpdateAssemblytitleAndAssemblydescriptionIn the assemblyinfo. VB file.

3.3 Localization

• UseAutosizeProperty where possible.
• Do not hide or overlap controls.
• Do not line up controls to create a sentence.
• Do not build strings by stripping out characters from another string. A common example is reusing a menu string in a dialog and removing the access key. this will not work for localized extensions ages because access keys are displayed differently in different extensions ages. for example, if you have & file in English, you wowould have file (& F) in Japan. use different strings if they have different purposes.
• Use culture-neutral graphics.
• Use only tahoma or MS sans serif fonts.
• In web forms, set the form'sPagelayoutPropertyFlowlayoutRatherGridlayout.
• In Web applications, follow the guidelines in HTML layout guidelines for web forms globalization.
• CurrentuicultureIs the property for the application UI Language. By default,CurrentuicultureWill match the system settingsUseruilanguage. This does not need to be overridden for samples, unless you want to show a localization sample.
• Use culture invariant overloads for the text manipulation methods and Classes listed.

  String. Compare	String. compareto	String. toupper
  String. tolower	Char. toupper	Char. tolower
  Caseinsensitivecomparer	Caseinsensitivehashcodeprovider	Sortedlist
  Array. Sort	Arraylist. Sort	Array. binarysearch
  RegEx

  ' Preferred. Dim isUri As Boolean isUri = (String.Compare(path, 0, "file:", 0, 5, _     True, CultureInfo.InvariantCulture) = 0) ' Not preferred. Dim isUri As Boolean isUri = (String.Compare(path, 0, "file:", 0, 5, True) = 0)

3.4 accessibility

• Use colors from the system tab of the color picker.
• Use accelerators for all menus, labels, buttons, and so on.
• Set control properties as described in the following table.

  Property	Setting
  Accessibledescription	A description of the control.
  Accessiblename	A name for the control.
  Accessiblerole	Default, or Reset this property if a control has another role.
  Tabindex	Set in a logical order.
  Text	All clickable controls shoshould have a keyboard access key (shortcut ).
  Font Size	Default or set to 10 points or larger
  Forecolor	Default
  Backcolor	Default
  Backgroundimage	Default

3.5 Security

Follow the guidelines in secure coding guidelines for the. NET Framework.

4 resources

General Reference

• McConnell, Steve.Code complete: A Practical Handbook of Software Construction. Redmond, Wa: Microsoft Press, 1993.

Security

• Howard, Michael, and David LeBlanc.Writing Secure Code. Redmond, Wa: Microsoft Press, 2001.
• Secure coding guidelines for the. NET Framework

Accessibility

• Microsoft Accessibility home
• Designed for Microsoft Windows? Optimized for accessibility, part ofDesigned for Microsoft? Windows?Logo Program.

Localization

• HTML layout guidelines for web forms globalization

Standards

• Design Guidelines for class library developers
• Fxcop, a code analysis tool.

 

Send comments to Microsoft.

? 2002 Microsoft Corporation. All rights reserved.