Coding Standards

From setiquest wiki

Revision as of 04:30, 10 June 2011 by Jrseti (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The source code for setiQuest and SonATA projects shall follow the following style guidlines.

Contents

Source code files should contain this header

/*******************************************************************************

  File:    <file name>
  Project: <project name>
  Authors: <authors>

  Copyright 2011 The SETI Institute

  <project name> is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

  <project name> is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
 
  You should have received a copy of the GNU General Public License
  along with OpenSonATA.  If not, see <http://www.gnu.org/licenses/>.

  Implementers of this code are requested to include the caption
  "Licensed through SETI" with a link to setiQuest.org.

  For alternate licensing arrangements, please contact
  The SETI Institute at www.seti.org or setiquest.org. 

*******************************************************************************/

Note: Tags such as <file name> are replaced with the tag value, such at "waterfallDisplay.java" (without the brackets or quotes).


Source code files should contain a brief explanation

The comments at the top of a source code file, after the licensing header mentioned above, should contain a brief explanation of what functionality the source code provides.

Tabs are not used for indentation

    printf("hello world"); // correct
	printf("hello world"); // incorrect

Some common sense required here: Where \s is a space, and \t is a tab. In this example, space after the \s and \t annotations, and the annotations themselves have been used for illustration; these should not be included in the actual code.

Also, you should configure your editor to automatically convert tabs entered to spaces. A tab should be 4 spaces.

Class, struct, and enum names are PascalCase and NOT prefixed

class MyClass { }; // class prefix is NOT C
struct MyStruct { }; // struct prefix is NOT C
enum MyEnum { }; // enum prefix is NOT E
Member, and enum constant names are (lower) camelCase
class MyClass 
{
	public:
		void helloWorld();
};

Member variables (public and private) begin with m_

class MyClass 
{
	public:
		MyClass* m_myClass1;
	private:
		MyClass* m_myClass2;
};

Enum constants are prefixed with k

enum MyEnum 
{
	kValue1,
	kValue2
};

Static variables are prefixed with s_

static MyClass* s_myClass;

Comments and debug messages need not be grammatically correct

// i'm using bad grammar. but i like to use full stops
DEBUG((CLOG_INFO "hello world"));

Multiline comments use single-line commenting (//)

// for long block comments, instead of using the slash asterisk
// comments, we use the two-slash comments

Function return types must go on the same line as the function name

// correct
int MyClass::helloWorld()
{
}

// incorrect
int
MyClass::helloWorld()
{
}

For functions, curly braces start on the next line after the function name

// correct
int MyClass::helloWorld()
{
	// ...
}

// incorrect
int MyClass::helloWorld() {
	// ...
}

For conditional statements, curly braces start on the next line

// correct
if (a == b) 
{
	// ...
}

// correct
for (int i = 0; i < a; i++) 
{
	// ...
}

// incorrect
if (a == b) {
	// ...
}

// incorrect
for (int i = 0; i < a; i++) {
	// ...
}

A space is used between operators and operands

// correct
a == b;
if (c == d) 
{
}

// incorrect
a=b;
if (c==d) 
{
}

No space is inserted after or before conditions within parenthesis

// correct
if (a == b) 
{
	// ...
}

// incorrect
if ( a == b ) 
{
	// ...
}

The void keyword is not used for functions that do not take parameters

// correct
void helloWorld();

// incorrect
void helloWorld(void);

The const keyword is used regularly

class MyClass 
{
	public:
		const char* helloWorld();
};

MyClass::MyClass(const char* helloWorld)
{
}

Spaces must exist between conditional statement parenthesis and the keyword

// correct
if (a == b) 
{
}

// incorrect
if(a == b) 
{
}

No spaces between type and reference and pointer operator

// correct
char* helloWorld;

// incorrect
char *helloWorld;

Pre-processor commands within #if are indented

// correct
#if HELLO_WORLD
#    include "HellWorld.h"

#endif

// incorrect
#if HELLO_WORLD
#include "HellWorld.h"
#endif

Pointers and references do not have prefixes

// correct
MyClass* myClass1 = new MyClass();
MyClass& myClass2 = *myClass1;

// incorrect
MyClass* p_myClass1 = new MyClass();
MyClass& p_myClass2 = *p_myClass1;

// incorrect
MyClass* pMyClass1 = new MyClass();
MyClass& pMyClass2 = *pMyClass1;

The left comparator operand is a variable

// correct
if (a == "hello world") 
{
}

// incorrect
if ("hello world" == a) 
{
}

The else statement always goes on a new line

// correct
if (a == b) 
{
	// ...
}
else 
{
	// ...
}

// incorrect
if (a == b) 
{
	// ...
} else 
{
	// ...
}

Constant names are upper case

C/C++:

#define MAX_BYTES 200

Java:

public static final int MAX_BYTES 200;


These guidelines were adapted from http://synergy-foss.org/pm/projects/synergy/wiki/CodeStyle. Thank you!

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox