OOP344 Temporary CodingStandards

Coding Standards for Team Temporary

Coding standards are important if we want code to be readable. Now the idea of these rules is that they're "common sense" with readability in mind. The most important section is the commenting section as it is basically arbitrary while all the others should be more or less common sense. In any case, the entire thing is up here for reference purposes. We should all attempt to follow these guidelines when writing code.

While no one will be prosecuted or killed if they forget one or more of these, the others will gently remind the person in question to follow the guidelines :)

Naming Conventions

• Camel Notation should be used for variable names and function names
  • ie myVar, bigInt, getNumber(), myFunction()
• Class names should always be First-Letter Capitalized
  • ie TestClass, DynamicStack, PeanutButter, Hammer
• Compiler directives should always be written in All Lowercase
  • ie #define, #ifndef
• Compiler definitions should be All Uppercase and should only use underscore where a gap is required
  • ie IO_CTL_LARGEFILE, SOME_DEFINITION
• Header file defines should be preceeded and followed with Two Underscores
  • ie __CIOL_H__, __IO_FORM_H__

Other Conventions

• Pointer declaration should emphasize the type with the "*" being pushed against the right side of the data type as opposed to the left side of the variable name.
  • ie char* str, int* num, void* addr
• Binary operators should have a space between them and their constituents (Note: This does not apply to unary operators such as ++ or []).
  • ie x = 7, z += y, int i = 10, judge = y > 5
• As well, please leave a space after every comma and every semicolon if something follows it.
  • ie foo(int firstInt, int secondInt, int thirdInt), x = bugSquish(parm1, parm2), for (int i = 0; i < 10; i++)
• When indenting, please indent by using two spaces as opposed to the tab character as the tab character changes size between systems
  • ie

if (x == y) {
  doStuff();
  doSomeMoreStuff();
}

• Finally, void should always be explicitly declared.
  • ie void doStuff(void), int getInt(void)

Statement Notation

The first left parenthesis on a function declaration should open immediately after the function name while the first left parenthesis on a loop declaration should open one space after the loop declaration.
ie Functions:

int hello(
char goodbye(
void getQuestion(

ie Loops:

while (
for (
do (

In the same sense, the first left parenthesis should immediately follow the function name when a function is called.
ie x = getInt(), someInt = y + bigSum(y, r)

Code Blocks

Both function blocks and loop blocks should open on the same line as the declaration statement preceding them; however, function blocks should open immediately after the last right parenthesis while loop blocks should open one space after the last right parenthesis.
ie Functions:

int hello(){
char goodbye(){
void getQuestion(void){

ie Loops:

while (var < 15) {
for (int i = 0; i < 15; i++) {
do (blah) {

Comment Blocks

All functions should have a comment block preceding them which should explain what the function does in a few brief sentences, what parameters it receives with each parameter having a section preceded by @param, and anything that the function may return preceded by @return at the end of the block. Try to keep things lined up so that they're easier to read.

Here is an example from Assignment 1 utilizing the io_strcpy() function:

/*Copies a given number of characters from one string to another.
 *Self copying is allowed. Does not stop at null-terminator, always copies 
 *the given number of characters. 
 *
 *@param const char* src  address from which to copy characters.
 *@param char* dest       address to which characters will be copied.
 *@param int n            number of characters to copy.
 *
 *@return the address of dest if copy was successful, NULL otherwise.
 */
char* io_strcpy(char* dest, const char* src, int n){

Commenting within the function should be generally organized, that's about it for in-function commenting.

As well, please ensure that a small commented header is at the top of every file (implementation if .cpp or header if .h). It should contain information such as the file name, project name, last modified date, last modified by, etc... Using the example of ciol.c from assignment 1, it should be in the following form:

/*  ##########################################################################
    Project:           OOP344 Assignment 1
    File Name:         ciol.c
    File Desc.:        Implementation file for console input output (CIOL) library.

    Last Changed By:   $Author$
    Last Changed Date: $Date$
    Last Changed Rev:  $Rev$
    ##########################################################################*/

When you commit the file, the $ keywords will be expanded automatically by svn to look like the following!

/*  ##########################################################################
    Project:           OOP344 Assignment 1
    File Name:         ciol.c
    File Desc.:        Implementation file for console input output (CIOL) library.

    Last Changed By:   $Author: ops344_093svn111 $
    Last Changed Date: $Date: 2009-10-28 12:14:38 -0400 (Wed, 28 Oct 2009) $
    Last Changed Rev:  $Rev: 8 $
    ##########################################################################*/

SVN is expanding these keywords because of the $Author$ $Date$ $Rev$ keywords and the svn:keywords property. Author will show the last person to have modified the file, Date will show the date that this file was last modified on, and Rev will indicate the revision at which this file was last changed.

The svn:keywords property has already been globally set and propagated so it's in full use right now and all files that need a header should have one in the specified format.

That's about it folks, feel free to add or remove anything if you feel so compelled but please consult the rest of the group first if it is a major change.
-northWind87