Few slides on coding guidelines

1. On Coding Guidelines myNameis dilawar(@Home), theLover( in Chennai), theLawWere(an Iranian Prof. in IIT Bombay) March 16, 2010 dilawar.in@gmail.com

2. 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)

3. Why do we need them?

4. 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 mistakescan be avoided. In start, It’s a burden to follow. At the end, it’s a pleasure that you’ve followed.

5. Naming conventions My 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(). Globalsshould be named meaningfully. Be generous!! Use recognizable names in English.

6. 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

7. 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.gassert). 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.

8. Classes, Variables and Functions Classes 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()

9. 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

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

11. 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.

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

13. Libraries… (Tips on STL) Don't usehash_mapsin 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. Usetypedefto 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.

14. Pointers vs References You will find it a very good practice always to verify your references sir. -- Martin RouthIf 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

15. 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

16. How to minimize bugs? Follow the guidelines!

17. 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/

18. Additional References The 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. HemantKarkare – 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