Phase Implementation Coding standards 1 Today Internal Comments

Phase Implementation: Coding standards 1

Today ] Internal Comments ] Programming Style ] Code Standards Janice Regan, 2008 2

Internal Comments ] Internal comments are the chief source of information about the source code, and thus are extremely important ] Use algorithm (pseudo code) as internal comments ] Purpose of internal comments: u explain WHY the code (subset of statements) is there i. e. , its purpose, rather than WHAT the code does Janice Regan, 2008 3

Internal Comments ] Various kinds of Internal Comments u Describe the purpose of the code useful u Explain WHAT a complicated piece of code does Useful in some situations (rare), for example highly optimized scientific applications following well know algorithms (FFT, …) Usually better to rewrite the code if it can be simplified u Repeat what the code does in natural language Much less useful, avoid this Janice Regan, 2008 4

Example of Internal Comments ] C example of an internal comment: using natural language // if allocation flag is zero if ( Alloc. Flag == 0 ) … ] C example of an internal comment that focuses on WHY // if allocating new member if ( Alloc. Flag == 0 ) … ] C example of using good programming style in addition to an internal comment that focuses on WHY // if allocating new member if ( Alloc. Flag == NEW_MEMBER ) … Janice Regan, 2008 5

Exercise ] Guess what the following Pascal chunk of code does? ] Are the comments useful? How could you make them useful? {Set Product to “Base”} Product : = Base; {Loop from 2 to “Num”} for i : = 2 to Num do begin {Multiply “Base” by “Product”} Product : = Product * Base; end; Janice Regan, 2008 6

Self-Documenting Code u Name of variables should describe their content/purpose u Name of methods should describe what they do u Internal comments should always add information. Janice Regan, 2008 7

Programming Style ] Simple and Readable ] Why? ] Guidelines: u Shorter code (must remain readable) u Code with fewer decisions u Revisit excessive nested logic: there is probably a better approach Janice Regan, 2008 8

Example: calculate minimum int minimum. Of 3(int i, int j, int k) { int minimum; minimum = k; if (i < k) { minimum = i; if (j < i) { minimum = j; } } else if ( j < k ) { minimum = j; } } Worst case 2 comparisons 3 assignments Best case 2 comparisons 1 assignment Janice Regan, 2008 9

Example: better calculate minimum int minimum. Of 3(int i, int j, int k) { int minimum; if ( k < j ) { if (k < i) minimum = k; else minimum = i; } else { if (j < i ) minimum = j; else minimum = i; } return minimum; Best Case: 2 comparison 1 assignment Worst Case: 2 comparisons 1 assignment } Janice Regan, 2008 10

Coding Standards ] Goals: u Unify programming style of s/w developers u Make code easy to read and maintain u Make code development more efficient u Make code more stable ] Approach: u define set of rules dictating how to formulate and comment code. Such a set of rules is know as a coding standard. Janice Regan, 2008 11

Why Have Code Standards? ] Each software developer has its own style ] A company can achieve code standardization by defining a set of code standards software developers must follow. ] This makes code easier to u Understand u Modify u Maintain Janice Regan, 2008 12

Coding standard not “arbitrary” ] A coding standard is not only to make the code look consistent ] Rules in the coding standard often impose practices that will u Improve the quality of code u Prevent common errors / save debug time u Create more stable code u Make code easier to maintain or expand Janice Regan, 2008 13

Content of Code Standards ] Layout of file and class ] Naming convention (e. g. Constants are ] ] capitalized) Style: for example indentation or declaration Format of method prototypes Programming constraints not specified by the language being used (initialize references to null…) Unified exception/error handling Janice Regan, 2008 14

Examples: Code Style Standards ] Always indent the body of a code structure such as a loop or if statement by 5 spaces ] Each line should contain at most one instruction ] Use blank lines to set off major control constructs ] Declare one variable per line of code Janice Regan, 2008 15

Examples: Code Quality Standards ] Variable and constant u Use variables and constants only for the purpose for which they have been declared and named u Avoid hard-coded literals, use constants instead u Always initialize variables ] Files u Open and close files explicitly u Open and close in same method Janice Regan, 2008 16

Suggested enhancements of Coding Standards ] You should define and use your own coding standard, based on standards available for the programming language you are using ] You may elected to use the enhancements given here. (or add your own). ] Use your coding standard so your submitted program will have a consistent style ] Remember to be consistent and use your standard for all code written Janice Regan, 2008 17

Possible Enhancements - 1 ] One declaration per line u It is self commenting. ] Beginning all comments in the same column ] Beginning all variable names in the same column u It is easier to read Example: int level; // indentation level int size; // size of table Object current. Entry; // currently selected table entry Janice Regan, 2008 18

Possible Enhancements - 2 ] The names of all attributes, methods, local variables, and parameters should begin with a lowercase letter and are to be descriptive. ] The names of all classes are to begin with an uppercase letter. private Graphical. Cell grid[ ][ ]; ] If a descriptive name contains more than one word the second and each successive word shall be capitalized Examples: private Graphical. Cell grid[ ][ ]; int patron. Name; string patron. Street. Address; Janice Regan, 2008 19

Possible Enhancements - 3 ] The names of attributes declared class constants are to be fully uppercased. ] Constant literal values should not be hard coded directly into the code but declared and their names are to be fully uppercased. Examples: static final int MIN_WIDTH = 4; my. Resource. status = AVAILABLE; Janice Regan, 2008 20

Possible Enhancements - 4 ] When declaring methods, the leading parenthesis and the first parameter (if any) are to be written on the same line as the method name. Each additional parameter is to be written on a separate line (with the closing parenthesis directly after the last parameter). Example: public int my. Complex. Funct( int a. First. Parameter, string a. Second. Parameter, float a. Third. Parameter, My. Class a. Fourth. Parameter, boolean a. Last. Parameter ) Janice Regan, 2008 21

Possible Enhancements - 5 ] The selection constructs (e. g. , "if", "else", and "switch") and the iterative constructs (e. g. , loops such a "while", "for", and "do") must be followed by a block ("{ }"), even if it is an empty block. Example: while( balance > 0. 0 ) { // Empty ! } Janice Regan, 2008 22

Possible Enhancements - 5 ] Always initialize references to null before using them. ] Always verify that a reference is not null before trying to access the memory you think it is referencing. ] Add any other enhancements you feel are appropriate u Your added enhancements should include a definition of a standard for indentation Janice Regan, 2008 23