On Coding Guidelines

myName is dilawar (@Home), theLover ( in Chennai), theLawWere (an Iranian Prof. in IIT Bombay)

March 16, 2010dilawar.in@gmail.com

The pursuit of goodness…

To be good, according to the vulgar standard of goodness, is obviously quite easy. It merely requires a certain amount of sordid terror, a certain lack of imaginative thought, and a certain low passion for middle-class respectability. -- Oscar Wilde (1854 - 1900)

Why do we need them?

Why Standard is Important?

• Person joining the group at later stage can pickup the code easily (once he is familiar with the standards).

• If care is taken to define the standard in such a way that it avoids problematic C++ idioms, then silly mistakes can be avoided.

• In start, It’s a burden to follow. At the end, it’s a pleasure that you’ve followed.

Naming conventionsMy name is Bond, James Bond! -- Ian

Fleming.

• It is very important to give meaningful names to all your constructs. A name like getAverageHeight() or get_avg_height() gives us much more information then calculate().

• Globals should be named meaningfully. Be generous!!

• Use recognizable names in English.

General Rules

• Thumb Rule : Bigger the scope, bigger the name!• Keystrokes Vs Marginal Information: Some names

do have standard abbreviation, for e.g. max. So, calling a variable maxLength gives us the same amount of information as maximumLength, but using the former saves some keystrokes

• If an abbreviation is contained in a name, it should not be used in all uppercase form. for example: use getHtmlPage ; not getHTMLPage

Constants, Enums and #define-s, Macros

• #define constants should be avoided in favor of const.• Constants and Enumerated types (enums) names should be distinguishable from

variables.There are few conventions for it: All uppercase name, with _ as word separator: MAX_ERRORS

Macros• Like global variables, macros should be avoided in favor of inline functions. But

some times they become unavoidable (for e.g assert). Special care should be taken while defining Macros which themselves declare variables. Macro names should be distinguishable from function names. Again, there are few conventions for it: – All uppercase name, with _ as word separator: GET_DATA()– suffix _m in name: getData_m()

• Variables defined inside macro body should NEVER clash with name in the scope calling the macro, or havoc will result. It is a good idea to have an entirely different convention for naming variables defined inside macro body.

Classes, Variables and FunctionsClasses• Name of a class should communicate its purpose. It is always beneficial to identify and name

all the major classes in the program at design stage itself. • Class name should start with an uppercase alphabet. class DiodeDude; class TerrificTransistor;Variables• Major variables, the ones which are shared by multiple functions and/or module should be

identified and named at design stage itself.• Variable name should start with a lowercase alphabet. kriti* firstKriti; Functions• Just like Variables. Anyway we have () to distinguish them. Prefixes should be used in functions

to make its meaning clear. This is specially useful for boolean functions. Some common prefixes are: – is : isTeamLeaderHome() – has: hasPages() – can: canOpenBottle() – get: getMaxLimit() – set: setPath()

File Naming and Organization

It is not so important to know everything as to know the exact value of everything, to appreciate what we learn, and to arrange what we know. -- Hannah More

`-- SampleProject |-- 00_Documents | |-- 00_User_Requirements | |-- 01_Design_And_Dev_Approach . .| |-- 12_Acceptance | |-- 13_References |-- 01_Hardware | |-- DaughterBoard | |-- README |-- 02_Software | |-- trunk | | |-- Module1 | | |-- Module2 | |-- tags | | |-- Tag1 | | |-- Tag2 | |-- branches | | |-- Branch1 | | |-- Branch2 | |-- README (This README contains the commit policy being followed.) |-- 03_Enclosure |-- 04 ... |-- 10_Releases |-- README

Classes

The loftier the building, the deeper must the foundation be laid. -- Thomas Kempis

Classes…

• Ensure that all the classes in your application have: default constructor, copy constructor, overloaded = operator

• identify classes that may need to modify the data of this class A and make those classes as friend of the class A.

• Separate the core algorithm/strategy to be implemented in a separate class.

• Ensure that your classes are not bloated. • Ensure that all derivable classes have virtual destructor.

Libraries

Libraries are not made; they grow. -- Augustine Birrell

Libraries… (Tips on STL)• Don't use hash_maps in STL, they are not portable across platforms (MSVC on

Windows does not support hash_maps!). In case you need to use a hash_map, take an approval from appropriate person.

• When using maps in STL, make sure you have defined the LessThan function object. Maps need this function object for ordering of elements that are inserted in the map. You don't need to write this function object in case the key element in your map is an integer.

• Use typedef to create iterator types or else the code becomes unnecessarily lengthy.

• For big data types (classes), use pointer to object instead of object itself to create STL data type (vector, set etc.). The reason for this is STL data types may move around their data lots of times. For big data, this means a lot of calls to copy constructor, which incurs run time penalty.

Pointers vs References

You will find it a very good practice always to verify your references sir. -- Martin Routh

If coding in C++, encourage use of references instead of pointers. In fact a pointer should typically be passed to a function only in cases where you need to execute something on the pointer being null condition.

Ref: http://www.embedded.com/story/OEG20010311S0024

Minimizing Bugs while Coding

If debugging is the art of removing bugs, then programming must be the art of inserting them. -- Guy is still unknown

How to minimize bugs?

Follow the guidelines!

Beware! We are living on a smarter planet?

Programming today is a race between software engineers striving to build bigger and better idiot-proof programs, and the Universe trying to produce bigger and better idiots. So far, the Universe is winning. -- Rich Cook

Embedded Dudes/Dudettes : http://www.ganssle.com/

Additional ReferencesThe man who doesn't read

good books has no advantage over the man who can't read them. -- Mark Twain (1835 - 1910)

http://www.cse.iitb.ac.in/~karkare/Gc/coding/#NameGeneral (Prof. Hemant Karkare – IIT Bombay, CSE)

I have not read the following but they can be useful for one who wants a deep insight.

1. http://cm.bell-labs.com/cm/cs/tpop Brian W. Kernighan and Rob Pike.2 . Effective C++, Scott Meyers.3. More Effective C++, Scott Meyers.4. Code Complete, Steve McConell.5. Writing Solid Code, Steve Maguire.6. http://www.possibility.com/Cpp/CppCodingStandard.html