Date post: | 05-Apr-2018 |
Category: |
Documents |
Upload: | pinakin-patel |
View: | 222 times |
Download: | 0 times |
of 12
8/2/2019 BI - Best Practice - Coding & Development
1/12
Blue Cross Blue Shield of Michigan is a nonprofit corporation and independent licensee of the Blue Cross and Blue Shield Association.
Business Intelligence CenterBusiness Intelligence Center
Best PracticesBest Practices
Coding & DevelopmentCoding & Development
For additional information, please contact:
Bennet Kurusumuthu
Manager: Self Service Architecture & App Development
Business Intelligence Center
mailto:[email protected]:[email protected]8/2/2019 BI - Best Practice - Coding & Development
2/12
B e s t P r a c t i c e sB e s t P r a c t i c e s
Coding & DevelopmentCoding & Development
Revision History
IDDate last
Updated
Revision Author Summary of Major Changes Made Approved ByApproval
Date
1 17-Aug-09 Pinakin Patel Initial Release
Page 2 of 12
mailto:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]8/2/2019 BI - Best Practice - Coding & Development
3/12
B e s t P r a c t i c e sB e s t P r a c t i c e s
Coding & DevelopmentCoding & Development
Table of Contents
Intent and Use of the Document ................................................................................. 4
Naming Conventions .................................................................................................... 5Variables .............................................................................................................................................. .... 5Constants ............................................................................................................................ ..... .............. . 6Routines .............................................................................................................................. ..... .............. . 6
Parameters ............................................................................................................................................................7
Objects 7
Formatting ..................................................................................................................... 8White Space, Indentation and Alignment................................................................................................. . 9Comments .............................................................................................................................. ..... ..... ....... 9
Error Handling ............................................................................................................. 10Appendix .................................................................................................................... 12
Appendix 1: Commonly Used Abbreviations/Acronyms .................................................................. ....... 12
Page 3 of 12
mailto:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]8/2/2019 BI - Best Practice - Coding & Development
4/12
B e s t P r a c t i c e sB e s t P r a c t i c e s
Coding & DevelopmentCoding & Development
Intent and Use of the Document
The purpose of this document is to foster the standardization and readability of coding and developmentthrough naming conventions and standards. The primary objectives in creating these conventions andstandards are as follows:
To be precise, efficient, complete, and unmistakable.
To be consistent with other language and development conventions.
To allow for better support, maintainability, and readability.
To better accommodate the growth and needs of the BCBSM Business Intelligence Center, this is a workingdocument and is intended to be continuously updated to reflect lessons learned and best practices.
Page 4 of 12
8/2/2019 BI - Best Practice - Coding & Development
5/12
B e s t P r a c t i c e sB e s t P r a c t i c e s
Coding & DevelopmentCoding & Development
Most of the developers are inclined towards writing code for higher performance, compromising reliabilityand maintainability. But considering the long term ROI (Return on Investment), efficiency and performancecomes below reliability and maintainability. If your code is not reliable and maintainable, you (and your
company) will be spending lot of time to identify issues and trying to interpret code.
Naming ConventionsOf all the components that make up a coding standard, naming conventions are the most visible andarguably the most important.Having a consistent standard for naming the various objects in your program will save you an enormousamount of time both during the development process itself and also during any later maintenance work.
Note: The terms Pascal Casing and Camel Casing are used throughout this document.
Pascal Casing - First character of all words are Upper Case and other characters are lower case.
Example: BackColor
Camel Casing - First character of all words, except the first word are Upper Case and other characters are lower
case.
Example: backColor
VariablesVariables are used very frequently in code; most statements contain the name of at least one variable. Byusing a consistent naming system for variables, we are able to minimize the amount of time spent huntingdown the exact spelling of a variable's name. Furthermore, by encoding into the variable's name someinformation about the variable itself, we can make it much easier to decipher the meaning of any statementin which that variable is used and to catch a lot of errors that are otherwise very difficult to find. The
attributes of a variable that are useful to encode into its name are its scope and its data type.
Variable names should use the following structure:
Syntax: Scope Type Body
Example: g s DescriptiveName
Length: 1 1 1 .. n
General Guidelines:
The prefix (first two characters) describes the scope and data type of the variable; for instance,lsFirstName - where the ls prefix indicates a local variable for First Name of type string.
The bodypart of the structure forms of a meaningful, descriptive name.
o The bodycannot contain embedded periods, underscores or other type-declaration characters;the only exception to this rule is when the use of such a character enhances the readability.
o The bodyshould use the Pascal Casingconvention. i.e. ProductLine, SalesByRegion.o Try of keep the length of the bodyas short as possible without compromising the readability of
the name to describe the purpose.
o For terms that are long and frequently used, abbreviations should be used to keep the namesto a reasonable length. For instance Rpt for Report, Init for Initialization, Qty for Quantity.(Please refer to Appendix 1 for a list of commonly used abbreviations). Note: If you do use anabbreviation, be consistent throughout your entire application.
Page 5 of 12
8/2/2019 BI - Best Practice - Coding & Development
6/12
B e s t P r a c t i c e sB e s t P r a c t i c e s
Coding & DevelopmentCoding & Development
o Common sense and judgment should when using abbreviations. For instance, if the bodyis justAddress, then do not abbreviate to addr.
Table 1.1: Variable Naming Conventions
Prefix Object Type Example
Scope and Usage Naming Conventions:
l Local defined within a specific function or procedure. lnPopulationCnt
g Global available globally to the entire application. gsModuleName
m Module defined in the general declarations area of the module; availableto the current module only
mvInquiry
Variable Type Naming Conventions:
a Array aDepartments
b Boolean, Yes/No bExists
d Date dCancelDate
i Integer iRowCnt
n Number; for general of Integers, Double, Float, Long nAccountNum
o Object oLstProduct
s String sAddress
v Variant vPerson
ConstantsDo not hardcode values such as strings, numbers, dates . Use constants instead.
Constants follow the same naming conventions as defined for variables above except that the body iscoded in ALL_UPPER_CASE with words separated by underscores.
Example(s): mnMARKUP_PERCENT
a numeric constant defined at the module scope level representing a Markup Percentage
RoutinesRoutine (function, procedure ) names should use the following structure:
Syntax:[Scope
][Type] Routin
eBody
Example: g s fun DescriptiveName
Length: 0 1 0 1 3 1 .. n
General Guidelines:
The scope prefixdescribes the visibilityof the routine and is only defined for global routines with the gprefix.
o Routines local to the module do not require a scope prefix
The type prefixis only used when naming functions it is not needed for naming procedures. Functionshave a return value, so their name should be prefixed to indicate the data type that is returned.
The routine prefixdescribes the type of routine; i.e. function or procedure.Page 6 of 12
8/2/2019 BI - Best Practice - Coding & Development
7/12
B e s t P r a c t i c e sB e s t P r a c t i c e s
Coding & DevelopmentCoding & Development
The bodyfollows the same guidelines as used for Variable names.Example(s): gbfunFileExists
a global function that checks if a file exists or not; return type is Boolean.
Table 1.2: Routine Naming Conventions
Routine Prefix Object Type Example(s)
fun Function dfunGetDate()
gbIsEmpty()
prc Procedure prcAddUser()
gprcSetTime()
Parameters
Always make sure you are absolutely clear about how each parameter is to be used in your routine. Forexample, is it used to communicate a value to the routine, to the caller, or to both?
General Guidelines:
Each parameter name is formed in accordance to the rules defined for variable names.
At the end of each parameter name, add an underscore followed by one of the words IN, OUT orINOUT as appropriate. Use upper case to really make these stand out in your code.Example(s): lnCustomerCd_IN
lsCustomerName_OUT
ObjectsObject names should use the following structure:
Syntax: Prefix Body
Example: txt DescriptiveName
Length: 1 .. 4 1 .. n
General Guidelines:
Theprefixdescribes the type of object; for instance, txtFirstName describes a text box object used forFirst Name.
When creating a prefix that does not exist in the list below, make sure it is unique; try to stick to a 3character representation of the object - only go to 4 characters if it makes the prefix more descriptive.
The bodyfollows the same guidelines as used for Variable names.
o Where possible, avoid using words in the description that can be derived from the prefix; forexample, rptSalesReport.
Table 1.3: Object Naming Conventions
Prefix Object Type Example
Cognos Specific Objects:
qry Query qryCostOfUsage
pg Page pgTypeOfService
Page 7 of 12
8/2/2019 BI - Best Practice - Coding & Development
8/12
B e s t P r a c t i c e sB e s t P r a c t i c e s
Coding & DevelopmentCoding & Development
parm Parameter use when creating a new parameter/prompt object parmEmployer
cnds Conditional Style use when defining a new conditional style variable cndsHidePHICols
General/Common Control Objects:
cbo Combo (Drop-Down) List Box cboLanguage
chk Checkbox chkReadOnly
cht Chart chtReferralsByDepartment
cmd Button / Command Button cmdOK
ctb Crosstab ctbUsageHours
dat Date, Date-Time, or Calendar object datPayPeriod
fra Frame fraSelectColor
frm Form frmSave
ftr Footer ftrCorporate
grd Grid grdWeeklyExpenses
hdr Header hdrCorporate
img Image imgBalloon
lbl Label lblDescription
lst List or List Box lstBusinessRules
map Map mapMichigan
mnu Menu mnuEdit
opt Option (Radio) Button optYes
rpr Repeater rprAddressLabel
rpt Report rptEarnings
rtx Rich Text Box rtxPhoneNum
sng Singleton sngAuthor
tbl Table tblMemberData
tmr Time/Timer object timMeetingBegin
toc Table of Contents tocBreifingBook
tre Tree object treGeography
txt Text Box txtFirstName
FormattingThe physical layout of code is very important in determining how readable and maintainable it is. We needto come up with a common set of conventions for code layout to ensure that programs incorporating codefrom various sources are both maintainable and aesthetically pleasing.
These guidelines are not hard and fast rules, less so than the variable naming conventions already covered.As always, use your own judgment and remember that you are trying to create the best possible code, andnot follow rules to the t. That said, you'd better have a good logical reason before deviating from thestandard.
Page 8 of 12
8/2/2019 BI - Best Practice - Coding & Development
9/12
B e s t P r a c t i c e sB e s t P r a c t i c e s
Coding & DevelopmentCoding & Development
White Space, Indentation and Alignment
General Guidelines:
Indent to four spaces at a time; avoid using the tab character.
The begin and endtags of control structures should be aligned to the same vertical level; Commentsshould also be in the same level as the code.
// Comment in same level as codeif ( ... ){ // Do something ...} else{
// Do something else
...}
// Comment not in same level as codeif ( ... ){ // -- tags not vertically aligned ... }else {... // not properly indented}
Use a single space before and after each operator and brackets.
if ( showResult == true ){
for ( int i = 0; i < 10; i++ ){
// Do something// ...
}}
if(showResult==true){
for(int i=0;i
8/2/2019 BI - Best Practice - Coding & Development
10/12
B e s t P r a c t i c e sB e s t P r a c t i c e s
Coding & DevelopmentCoding & Development
a modification/amendment history
Here is an example of a sample header block:
/*==============================================================================
NAME: mprcRoutineName
PURPOSE: This Procedure is used to ...
PARAMETERS: 01. lnAccountID_INUnique ID that represents an Account in TBL_ACCT.
02. lsAccountName_OUTName of the Account that ties to the ID.
RETURN: N/A
===============================================================================M O D I F I C A T I O N L O G :
D a t e A u t h o r D e s c r i p t i o n--------- -------------- ----------------------------------------------------01-Jan-09 P.Patel Initial Release
-----------------------------------------------------------------------------*/
The truth of the matter is that you will not write one of these for every routine. For many routines, a few linesof comments at the top is all you need to convey all the information required.For significant routines, until you can write one of these you haven't thought the processing through enoughto start coding. If you don't know what's in that header, you can't start maintaining that module. Nor can youhope to reuse it without requiring someone else to read through the code to decipher what is going on.
In-line Comments
In-line comments are comments that appear by themselves on a line, whether they are indented or not.In-line comments are the Post-It notes of programming. This is where you make annotations to helpyourself or another programmer who needs to work with the code later.Use In-line comments to make notes in your code about
what you are doing
where you are up to
why you have chosen a particular option
any external factors that need to be knownDo not document what is self-evident from the code. Comment only what is not readily discernible from thecode.
Error HandlingThe ideal situation is to have an error handler around every bit of code and that should be the starting point.This is not always achievable in practice for all sorts of reasons and it is not always necessary. The rule is,however, that unless you are absolutely sure that a routine does not need an error handler, you should atthe very least create a handler around the entire routine.
User Defined Error Messages
Page 10 of 12
8/2/2019 BI - Best Practice - Coding & Development
11/12
B e s t P r a c t i c e sB e s t P r a c t i c e s
Coding & DevelopmentCoding & Development
Error messages should help the user to solve the problem. Never give error messages like "Error inApplication", "There is an error" etc. Instead give specific messages like "Failed to update database.Please make sure the login id and password are correct."
When displaying error messages, in addition to telling what is wrong, the message should also tell whatshould the user do to solve the problem. Instead of message like "Failed to update database.", suggestwhat should the user do: "Failed to update database. Please make sure the login id and password arecorrect."
Show short and friendly message to the user. But log the actual error with all possible information. Thiswill help a lot in diagnosing problems.
Error LogThe error handler should log details about the error condition such as:
the name of the module
the name of routine being executed
error number and error message thrown by the application (i.e. oracle, java, )
user defined error message. i.e. unable to retrieve security token.
parameters and their values (optional).
Page 11 of 12
8/2/2019 BI - Best Practice - Coding & Development
12/12
B e s t P r a c t i c e sB e s t P r a c t i c e s
Coding & DevelopmentCoding & Development
Appendix
Appendix 1: Commonly Used Abbreviations/Acronyms
General Guidelines:
The acronym describes the shorthandversion of the full text.
Use acronyms anywhere in the bodypart of a naming convention.
Use your judgment as to what character case to use for the acronym. for example, you could use eitherUserId or UserID for the User Identifier text. The later of the two exhibits greater readability.
Acronym Description
Acct Account
Addr Address
Amt Amount
App Application
Atr Attribute
Bgd Background
Cd Code
Cnt Count
Col Column
DB Database
Dbd Dashboard
Desc Description
Dev Development
Dim Dimension
DM Data Mart
Doc Document
EDW Enterprise Data Warehouse
Err Error
Fgd Foreground
Fld Field
Fmt Format
Hist History
Id Identifier
Idx Index
Ind Indicator
Info Information
Lkp Lookup
Mdl Model
Msg Message
Num Number
Pcnt Percent
Prd Production
Prg Program
Prmt Prompt
Pwd Password
QA Quality Assurance
Qty Quantity
RS Recordset
Ref Reference
Rpt Report/Reporting
SS SnapShot
Spec Specification
Std Standard
Stg Staging
Tmp Temp
Trx Transaction
UAT User Acceptance Testing
Vw View
Xfer Transfer
Page 12 of 12