Introduction

These standards have been modified from the Standard Coding Standards for the Java Programming Language from Sun Microsystems, to suit the Visual Basic and ASP programming lanuages.

Documenting Files

Guidelines

1.	All pages start with comment tags, which describe the functionality of the page, author and version. For ASP pages, the parameters need to be defined for values obtained from the querystring or from a form post.
2.	All comments start with the standard ‘ character.
3.	The comments are broken into 2 parts, the name of the tag and it’s value.
4.	The name and the value are separated by a tab character.

Supported Tags

Tag	Description	
@desc	Description of page	
@author	Author of page	
@version	Version of  Page	
@param	ASP - Parameters passed to this page.
VB - Any properties to be set before class or form is invoked.
(optional)	
@usage	Typical usage scenario (optional)	
@example	Example of usage (optional)	
@see	Related Pages (optional)	

Examples

Visual Basic

'@desc      This module contains generic functions used in various projects.
'@author    Balaji Srinivasan
'@version   1.0

ASP

<%
'@desc		This file contains methods for retrieving functions from the 
'		Customer database. All functions use stored procedures to retrieve
'		information from the database.
'@author    	Balaji Srinivasan
'@version   	1.0
%>

ASP with QueryString or Form Post Data

<%
'@desc		This file shown the customer information about a particular
'		customer. This is based on which type of view is selected by the '			user.
'@author    	Balaji Srinivasan
'@version   	1.0
'@param	CustomerID	The ID of the customer 
'@param	View		The type of view to show.
‘@usage	This file is used when the user clicks on a customer from the list ‘		of customers.
‘@example	http://server/ThisFile.asp?CustomerID=3&View=ListView
'@see		CustomerList.asp
'@see		CustomerAdd.asp
'@see		CustomerModify.asp
'@see		CustomerDelete.asp

%>
Documenting Procedures and Functions

Guidelines

1.	Before all functions and subs, a comment block should be added, which describes the function.
2.	The comments are broken into 2 parts, the name of the tag and it’s value.
3.	The name and the value are separated by a tab character.
4.	This comment block describes the procedure, it’s parameters, usage, examples and return values.
5.	All comments within the procedure itself are commented in the usual way.

Supported Tags

Tag	Description	
@desc	Description of procedure	
@author	Author of procedure (optional)	
@version	Version of procedure (optional)	
@param	ASP - Parameters passed to this page.
VB - Any properties to be set before class or form is invoked.	
@usage	Typical usage scenario (optional)	
@example	Example of usage (optional)	
@see	Related Pages (optional)	
@return	Return Value of the function	
@since	Version of this file when this procedure was added.	

Examples

Example 1 – Sub with no return value

'@desc     	This is a generic function to do mass replace, in a batch process,
'         	within a string.
'@param	cInputString    The input string
'@param     	cOutputString   the string which will contain the changed values
'@param     	oReplaceTags    The object which contains the list of key value 
'    	     	pairs which need to be replaced
'@usage     	Create a Settings object, and add all the strings to be replaced.
'           	Put the string to be replaced in key, and the new string in value.

Public Sub SimpleParse(ByVal cInputString As String, _
                    ByRef cOutputString As String, _
                    oReplaceTags As Settings)

Dim oTag As Setting
For Each oTag In oReplaceTags
     cInputString = Replace(cInputString, oTag.Key, oTag.Value)
Next

cOutputString = cInputString
End Sub

Example 2 – Function with return value

'@desc      This function is a wrapper around the GetPrivateProfileString API 
'	      call.
'           It reads a value from an INI file and returns that value.
'@param     cIniFile        The INI file from which to read the settings
'@param     cSection        The section of the ini file from which the setting ' 				 will be retrived
'@param     cKey            The key to search for
'@param     cDefaultValue   The default value to be returned in case no value 
'	                     is found
'@return    GetIniValue     Returns the value if found, or the passed default 
'                           value
Public Function GetIniValue(cIniFile As String, _
                        cSection As String, _
                        cKey As String, _
                        cDefaultValue As String) As String
Dim iBytes As Long
Const iMaxSize = 32767
Dim cKeyValue As String

cKeyValue = Space(iMaxSize)
iBytes = GetPrivateProfileString(cSection, cKey, cDefaultValue, cKeyValue, iMaxSize, cIniFile)
cKeyValue = Mid$(cKeyValue, 1, (InStr(1, cKeyValue, Chr(0))) - 1)
cKeyValue = Trim(cKeyValue)

GetIniValue = cKeyValue
End Function