National Database System (NDS-32)
Macro Programming Standards For Microsoft® Word
Annex - 8
Objectives
A well-defined system needs to follow standards. The philosophy behind it is consistency, ease of remembrance and maintenance.
Scope
These standards apply to macros developed in MS Word (for reports).
Format for the Source Code Files
Functions / Subroutines In-line Documentation
Each function or subroutine within a form or a module should start with a comment box (header), which should be the main comment for that function or subroutine, followed by the function or subroutine. It should be as follows
‘***************************************************************************** ‘* Name of the function
‘*
‘* Date Written ‘*
‘* Author ‘*
‘* Description of the function ‘*
‘* Parameters passed to the function, if any, along with their type and description ‘*
‘* Parameters returned by the function, if any, along with their type and description ‘*
‘**************************************************************************** ‘*Amendment History
'****************************************************************************** '* Date Amended * Amendment * Author
'* * *
'* * *
'******************************************************************************
Comments should be placed within the code itself only when it truly makes the code more understandable. It should be placed within the blocks involving complex processing.
In addition, when calling functions or subroutines that are not in the same form or module, a comment should be placed adjacent to or above the function or subroutine call, mentioning the name of the form or module in which the function or subroutine resides. This helps developers, who are maintaining and/or understanding programs written by others, to navigate through the code.
Rules for Indentation
The following points should be applied while writing a program. 1. Spacing
• Always put separate statements on separate lines
• Never let long statements wrap around lines. If a statement requires more than one line, break it up.
2. Variable declarations
• All variables shall be explicitly declared.
• The declaration section of every form and module shall include the "Option Explicit" keyword.
• When declaring variables, group the same type of variables together. 3. Indentation
• Use tabs for all indentation and set the tab value to 4. 4. SQL Statements
• All the SQL Statements written in the Visual Basic code should be in upper case.
Global
Comments should accompany declaration of every global variable stating the usage of the variable. Try to use as few global variables are possible.
Naming Conventions
The name of the variable should reflect the data stored/referred by the variable.
The scope of the variable depends on how and where it is declared
Scope Declaration Location
Local Dim, Static, Private, Public A procedure anywhere Module or
Form
Dim, Private, Public Declaration section of a module or form Global Global Declaration section of a module
• The variables should not be more than 32 characters long and should not have any punctuation marks or numbers.
• All the variables should have a minimum two character prefix. The first character signifies the scope of the variable (for eg. Local variables is identified by letter 'l', global variables by the letter 'g' and the module level variables by letter 'm'. The second character shall signify the type of the variable.
• After the two character prefix there shall a underscore followed by a string which best describes the variable. The descriptive part shall follow Hungarian notation and underscores could be used for readability.
Data Type Prefix Example
Integer I li_Test (for local)
Long L gl_Test (for global)
Double D Md_Test (for module)
Boolean B lb_Flag Byte By Lby_Code Currency Cu Lcu_Commission String S gs_Test Variant V lv_Test Control Ctl Lctl_Test Date Dt ldt_LoginDate Xarray Xa Lxa_Company
Record Rec Rec_Employee
The standard prefix for different types of controls (Object Variables) objects shall
be as follows:
Object Prefix Example
Project Prj prj_NDS
Form Frm_nds frm_nds_A
Check box chk chk_ReadOnly
Combo box cbo cbo_Bulletin
Command button cmd cmd_Update
File list box fil fil_Source
Frame fra fra_Materials
Grid grd grd_recalls
Image Img Img_logo
Label lbl lbl_Name
Line lin lin_straight
List box lst lst_EmpCodes
Menu mnu mnu_FieldResearch
Module Mod Mod_reportACommon
Option button opt opt_suppress
Picture box pic pic_logo
Progress Bar pgb pgb_Copy
Status Bar stb stb_MDI
Text box txt txt_Address
Toolbar tlb tlb_MDI
Constants
All application constants shall be named as variables except they shall be in upper case and an underscore separates the prefix and the name.
e.g. : Global Const GI_FINDFILEERROR = 1
Function / Subroutine name length shall not exceed 32 characters. This shall be prefixed with ‘g’ (global) or ‘l’ (local) followed by 'fn' for function and ‘sb’ for subroutine . This shall be followed by an underscore and then a string which best describes the function or subroutine.
e.g. : Function gfn_ArrayQuickDecode (lvDataValue as Variant) Sub lsb_ConvertDataType (liDataValue as Integer)
Files
All these files shall not be more than 32 characters long. They shall not have any punctuation marks and shall not start with a number.
The names shall have a prefix of the module to which they belong to followed by an underscore. The rest of the file name shall be sufficiently descriptive to relate to the its purpose and may have underscores to improve readability. The extension of the file shall indicate the type of program file.
The different extensions indicating type of files will be the following:
Extension Type of file
.vbp Visual Basic Project
.bas Visual Basic Module
.cls Visual Basic Class
.frm Visual Basic Form / MDI Form
Examples of program names are as follows:
File Name Description
NDS_frm_A Form for form A NDS_rpt_A Report for form A NDS_frm_Login Common Login form
Macros
All macro names should be in capital letters. Words inside the name should be separated by an underscore.
Conventions for Comments in the Code
For Functions:
Each function will have the following information associated with it : 1. Purpose
3. The names of the functions that are called from this function
4. The names of the functions that call this function (the list may not be exhaustive)
For IF:
Each conditional statement may also be commented. The commenting is necessary for conditional statements with complex or non-apparent conditions. The comment should include :
1. The condition
2. What happens if it is true 3. What happens if it is false
Commenting Changes to the Code
All changes made to the code should be properly commented using the
change comment.
Error Messages
All standard exceptions are to be handled. The messages are to be displayed preferably from the error messages table.
Additional Conventions
• All names (e.g. name of the author) should be Datamatics Ltd.
• Enumerated variables should be used when integer variables can take only certain predefined values only.
• Try to use as few exit points from a function as possible.
• Try to keep the code as simple as possible.
• Use parenthesis to avoid precedence ambiguity. XXX
