bi - best practice - coding & development

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

[email protected]
mailto:[email protected]:[email protected]


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


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]


3/12



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]


4/12



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


5/12



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


6/12



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


7/12



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/12



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


9/12



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


10/12



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


11/12



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


12/12



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

bi - best practice - coding & development

Documents