Programming Style

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>

转载于:https://www.cnblogs.com/RobotTech/archive/2007/05/28/762316.html