National Database System (NDS-32) Macro Programming Standards For Microsoft Word Annex - 8

Transcription

1 National Database System () Macro Programming Standards For Microsoft Word Annex /28/2000 /10:23 AM ver Doc. Id: RNMSWS softcopy : word page : 1/6

2 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. 02/28/2000 /10:23 AM ver Doc. Id: RNMSWS softcopy : word page : 2/6

3 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 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 Dim, Private, Public Declaration section of a module or form 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. The standard prefix for different data types and objects shall be as follows: 02/28/2000 /10:23 AM ver Doc. Id: RNMSWS softcopy : word page : 3/6

4 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 and Subroutine 02/28/2000 /10:23 AM ver Doc. Id: RNMSWS softcopy : word page : 4/6

5 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.vbp.bas.cls.frm Type of file Visual Basic Project Visual Basic Module Visual Basic Class Visual Basic Form / MDI Form Examples of program names are as follows: File Name NDS_frm_A NDS_rpt_A NDS_frm_Login Description Form for form A Report for form A 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 2. Input arguments and their semantics 02/28/2000 /10:23 AM ver Doc. Id: RNMSWS softcopy : word page : 5/6

6 For IF: 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) 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 Error Messages All changes made to the code should be properly commented using the change comment. 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 /28/2000 /10:23 AM ver Doc. Id: RNMSWS softcopy : word page : 6/6