Advanced Computer Science Lab Coding Style & Documentation

1. Advanced Computer Science Lab Coding Style&Documentation

2. Indentation • Tabs are 8 characters, so indentations are also 8 characters. • if you need more than 3 levels of indentation you should fix your program.

3. Indentation • Easy to read • Used to warn when functions are nested too deep

4. Placing Braces • preferred way ( Kernighan and Ritchie), is to put the opening brace last on the line, and put the closing brace first • Functions:

5. Placing Braces • Exceptions for closing bracket on its own line:

6. Naming • C programmers do not use cute names like ThisVariableIsATemporaryCounterBUT rather “tmp” • GLOBAL variables (to be used only if you _really_ need them) need to have descriptive names, as do global functions

7. Naming • function that counts the number of active users • GOOD:"count_active_users()" • BAD:"cntusr()" • LOCAL variable names->short • BAD: loop_counter • GOOD: i or j

8. Functions • Short & Sweet • Max 1-2 screens of text (80x24) • maximum length of a function is inversely proportional to the complexity and indentation level • 5-10 local vars or something’s WRONG • =>rethink, split in smaller pieces

9. Commenting • Good • Danger: over commenting • DON’T explain HOW code works BUT WHAT it does (&WHY) • Not too many comments inside function, BUT at the head

10. Classes- Suggestions • public variables must begin with m like mFooVar(m=member) • protected variables must begin with mt, like mtFooVar and methods with t, like tFooNum(). (t=protected) • private variables must begin with mv, like mvFooVar and methods with v, like vFooLone().(v stands=private)

11. Classes- Suggestions • All public, protected and private variables must begin with uppercase after m like F in mFooVar. • All pointer variables must be prefixed with p, like • Public variables mpFooVar and methods like FooNum() • Protected variables mtpFooVar and methods with t like tFooNum() • Private variables mvpFooVar and methods with v like vFooNum()

12. Classes- Suggestions

13. You have made a mess… • Use “indent” with "-kr -i8" (stands for "K&R, 8 character indents") • See “man indent” for more • Indent does not fix bad programming!

14. Documentation Style • Standard C++ Comments • -Allow maintenance of code by people not involved in its development. • -Allow understanding of requirements, inputs and outputs, algorithms, and software design techniques, when reviewing code. • -Allow understanding of code structure for purposes of reusability

15. Doxygen • mainly extracted from the comments in header files • description of a class is placed before the class statement (/** .... */ or ///…) • Can embed HTML tags • Commands: @class, @author, @date, @return, @param • > doxygen –g doxyfile.cfg • > doxygen doxyfile.cfg