4.3 Program Documentation
4.3.1. A program must contain the following head comment block:
/***************************************************
Program Name :
Module :
Function Tree : identifies which part of the function menu tree it is called (for ASP)
Functionality : describes the functionality provided by the program
Parameter List : (for Components)
Return Codes : (for Components)
Remarks :
******************************************************/
4.3.2.The program should have sufficient documentation to explain different sections of the program.
4.4 Programming Style
Provide guidelines to standardize programming style in term of file, directory, class, variable, web control naming, constant, etc. This would help to ease program readable and maintenance.
4.4.1. File Naming
In general, file name uses the prefix of module and followed by underscore. For example: adm_, oe_, bl_,… Files for common module do not have such prefix.
Namespace
The recommended name space for StarLight framework classes is, StarLight, followed by project name and the class name, e.g. StarLight.CommonApp.CmFunc
As for other customized classes, the namespace for both web form and class should follow the directory structure of the file. Between root directory and sub directory separated by full stop. First character for each directory name is in upper case.
Server Control Naming
Each web control must have prefix as defined below. First character for each subsequent word is in capital letter.
Controls Prefix
Data Connector dcn_
Data Adapter dap_
Data Set dst_
Data View dvw_
Data Table dtb_
Data Row drw_
Data Column dcl_
TextBox txt_
Label lbl_
ListBox lbx_
Button (for all button types) btn_
Drop Down List drp_
Data Grid dgd_
Data List dls_
Check Box chk_
Check Box List cbl_
Radio Button rbt_
Radio Button List rbl_
Image img_
Panel pnl_
Place Holder phd_
Calendar cal_
Table tbl_
Validator Require Field vrf_
Validator Range vrg_
Validator Regular Expression vre_
Validator Custom vcu_
Validator Compare vcp_
Validator Summary vsm_
Class property/method
First character of each word is in capital letter.
For example: Conn, SQLSelect(), GetUserID().
Local variable, parameters and query string
First character of first word is in lower case. First character of the subsequent word is in upper case. For example: sqlText, userContactNo.
Session variables
For common session that is defined in GlobalUnit must have GB_ prefix in front. First character of each subsequent word is in capital letter. For example: GB_AppRoot, GB_SysUserID.
For each module must follow the module prefix in front and first character of each subsequest word is in capital letter. For example: OE_TermEffDate.
Constant/Enum
Any declaration of constant variable or Enum data structure must be in capital letter for all of the letters.
Maximum number of lines for function/file
In order for the program to be more readable and easy to maintain, maximum number of lines of codes for function is restricted to 100 – 150 lines. The maximum lines of codes for a file/class is 500 – 700.
Comments on codes
Comments for method is on the top of the method. The escape character used is ‘///’. It will generate and xml format of comment. This is used to automate the generation of code comment report in html format.
Comments for particular line of code use ‘//’ escape character.
For long description of codes use ‘/*… */’. Minimal use of such escape character as it can be implemented by using ‘///’.
Xml file coding standard
For all node name and attribute, use title case, similar to class public property and method naming.
Example:
<XmlNode FirstAttribute="Value String" SecondAttribute="string value">
</XmlNode>
Try to reduce the number of nodes. If a field is not repetitive, store the field as a attribute instead of creating a new node for it.
Example:
(Recommended)
<DataSource TableName="US_FUNCROLE"></DataSource>
vs
(Not Recommended)
<DataSource>
<TableName>US_FUNCROLE</TableName>
</DataSource>
Use attribute instead of node value as far as possible. Unless the value is multiple line or very long. For example,
<BillInfo AcctNo="012345"></BillInfo>
<AddressInfo>
1 HillCrest Road
STA
Singapore 288893
</AddressInfo>
For Yes/No fields, we will use Y/N (upper case) to store the value. For example,
<ValidationInfo CheckNull="Y" CheckRange="Y" CheckFormat="N"> </ValidationInfo>