coding standard

MSI coding standard

                                                            By John Huang

1. Objective
   
   1. To make the code easy to understand, by the original developer, and by other developers who utilize the code.
   2. To make the code easy to maintain, by the original developer, and by other developers, and to keep a consistent style over the life cycle.
   3. To make the code easy to type.
2. Class name
   
   1. Regular class should start with C. For example, CVideoFile.
   2. Utility classes, which contains only static members, should start with U. For example, UStringUtils.
   3. Stack classes, which use its constructor and destructor to store and restore some states, should start with St. For example, StWaitCursor.
   4. Each class should reside in one .cpp file and one .h file. Each file should contain only one class. The file name should be classname.cpp and classname.h. Do not omit the prefix C, U, or St.
   5. The .h file should be scoped with

#ifndef _H_classname_
#define _H_classname_

…

#endif

3. Function name
   
   1. Function names should be complete words instead of abbreviations.
   2. Each word in the function name should start with capital letter.
   3. Function names should be descriptive.
4. Parameters
   
   1. Each parameter should use prefix to indicate whether it is input value, or output value, or both

                      i.      Use “in” to indicate it is an input value. 
                      ii.      Use “out” to indicate it is an output value. 
                      iii.      Use “io” to indicate it is both input and output.

2. There is no need to use prefix to indicate the data type.
3. After the prefix, the parameter name should be complete words instead of abbreviations.
4. Each word should start with capital letter.
5. Each parameter should contain one meaning only.
4. Return value
   
   1. The return value should contain one meaning only.
   2. If multiple return values are needed, use pointer or reference parameters with “out” as prefix.
   3. Use enum type for return values that are flags.
   4. If the meaning of a return value is not obvious, it must be documented in the .h file.
5. Function body
   
   1. Block start and block end ( “{“ and “}”) should be on their own line.
   2. The block end should match its block start vertically.
   3. Normally, a function should contain less than seven lines of code.
   4. A function should never exceed the viewable area of VC. (The complete function must be viewable in VC without scrolling)
   5. Local variables should be declared just before they are used (as late as possible).
   6. Local variables should be complete words instead of abbreviations.
   7. The first word of local variable name should start with lower case. Other words in the name should start with upper case. For example, “newColor”.
6. Project
   
   1. Library projects should have a name starting with “Engine”.
   2. Projects containing internal data logic should start with “Data”.
   3. Projects containing user interface code should start with “View”.
   4. Projects that build the final exe should start with “App”.
   5. Resource projects should contains the language resource should start with “Language”.
   6. Projects that build filters should start with “Filter”.
   7. App projects should contain as little code as possible.
7. Text Format
   
   1. Use standard VC default settings for code editor format.
   2. Do not use third party code editors to avoid different look on different PCs.
   3. The width of the code should fit within the VC code editor window without horizonal scrolling.
   4. The vertical length of the each function should fit within the VC code editor window without vertical scrolling.
8. Code
   
   1. NEVER use “goto”.
   2. Do not “return”, “break” or “continue” in the middle of a loop. They make the code harder to understand, and easier to have mistakes.
   3. Do not “return” in “if…else…” unless there is no other code after the “if…else…” blocks.
9. Assembly
   
   1. Assembly code should use MS assembler.
   2. Assembly code should be accompanied by corresponding c code.