OSSIE Development Procedures & Policies

This document describes coding and development guidelines to be observed in OSSIE development. These guidelines cover coding style, documentation, code reviews, repostory usage, and testing. The objective of these guidelines is to improve software quality by providing consistency accross all development efforts and phases.

OSSIE Coding Style

The OSSIE Coding Style is based on the "Linux Kernel Coding Style" cite: linuxkernelcodingstyle:web

A summary of our modified version of the Linux coding style is presented here as a quick reference.

Indentation

Tabs are 4 characters; thus, indentations are also 4 characters. This should be observed for both C++ and Python code.

Placing Braces

The OSSIE preferred style is to put the opening brace on the conditional line, and put the closing brace on its own line, for example:

if (x is true) {
// we do y
}

The closing brace is alone on a line, except in cases where it is followed by a continuation of the same statement, e.g. a while in a do-statement or an else in an if-statement, like this:

do {
// body of do-while loop
} while (condition);

and

if (x == y) {
// ..
} else if (x > y) {
// ...
} else {
// ....
}

The only exception to this rule is functions and methods, whose opening braces are at the beginning of the next line, viz.

int function(int x)
{
// body of function/method
}

Naming

Medial capitals (camelCase) is used in OSSIE development. Variables should be named using lowerCamelCase, while functions and abstract data types should use UpperCamelCase. Macros should be named using upper case letter with dividing underscores THIS_IS_AN_EXAMPLE. Here is a generic example:

#define MACRO_DEFINITION

class ClassName{
int variableName;
void MethodName(void);
};

Global variables (to be used only if you really need them) need to have descriptive names, as do global functions.

Local variable names should be short, and to the point. A random integer loop counter should probably be called i. Calling it loopCounter is non-productive, unless there is a chance of its purpose could be misunderstood.

Functions & Methods

Following the UNIX philosophy, functions should do specifically one thing, and do it well. Ideally, they should fit on one or two screenfuls of text. However, it is OK to have a longer function if it is conceptually simple (e.g. a long switch case). The more complex the function, the closer it should adhere to the maximum limits. All helper functions must have descriptive names.

As a general guideline, if there are more that 10 local variables, the function should be split into simpler pieces.

Functions with long names or parameter lists that cannot fit into one screen width should be split into multiple lines. Here is a C++ example:

CORBA::Object_ptr MyAwesomeMethod(unsigned short * myFirstInput,
float mySecondInput,
CORBA::Octet myThirdInput,
int & myFirstOutput)
throw(CF::PortSupplier::UnknownPort,
CORBA::SystemException,
CF::PropertySet::PartialConfiguration);

Similarly, Python definitions whose inputs list exceeds the width of a window (approximately 80 characters) should be split into multiple lines. An example is shown below.

def sendTimingMessage(self, componentName, portName, functionName, \
description, numberSamples):
self.cName = componentName
self.pName = portName

Commenting

Comments are required to explain what the code does, not how. It is preferred that comments appear at the head of classes, functions, and variables, explaining what they do, and why. Comments inside the body of the function should be avoided except for small comments to note or warn about something out of the ordinary (e.g. something particularly clever or ugly).

Declarations for C++ (usually .h files) should include comments following the Doxygen cite: doxygen:web style. Definitions should be commented, but it is not necessary to use the Doxygen format.

There are three preferred formats for creating comments recognized by Doxygen, shown below.

/// Simple comment used before declaration
int myVariableDeclaration;

/** Extended comment (usually longer in description)
* to be used before declaration
*/

int myVaraibleDeclaration;

int myVariableDeclaration; ///< simple in-line comment

Here is a more complete example of a class declaration with comments recognized by Doxygen.

/** \brief Here is a brief doxygen-friendly description of a class
*
* Here is a more detailed description, including design,
* purpose, and limitations.
*/

class MyClass {
public:
/// Default constructor
MyClass();

private:
/// Disallow copy constructor
MyClass( MyClass & );

int myFirstVariable; ///< description
int * variablePtr; ///< description
};

Comments should be meaningful and simple. Remember that they will ultimately appear in our Doxygen documentation. Comments that do not add valuable information for documentation but that are necessary to explain something (e.g. those inside the body of a function) should not follow the Doxygen style

Comments should be updated before committing to subversion.

Documentation

Documentation for C/C++ code shall be generated using Doxygen cite: doxygen:web. Aside from class descriptions (see section on commenting), OSSIE components require a main documentation. This page is created by Doxygen with the information provided inside the file documentation.txt. This file shall be located at the top of the component's directory and follow the format below.

/*! \mainpage Project/Component Name

\section description Basic description
Include a basic description of the project here

\section properties Properties
This section details the properties

\subsection prop_property_name Property Name (DCE:xxxx-xxx-xxx-xxx-xxxx)

\section interfaces Interfaces

\subsection port_portName Port: "portName"
There is a description for each port

\section dependencies Software build dependencies
- Dependency 1
- Dependency 2

\section algorithm Detailed Description of Algorithm

\section status Status and history

\section references References

*/

Although Doxygen does not directly support python code, documentation is already built into the Python language and can be accessed by executing help(myPythonClass) in the Python IDE. An example of such documentation is presented below.

class myClass(self):
"""
Here is a description of the class in triple quotes. Note
the indentation.
"""


def __init__(self):
"""Constructor."""
self.name = "Dead parrot" # initialize name

def PrintName():
"""Prints the name to the screen."""
print "My name is " + name

OSSIE Code Reviews

There will be two reviews for every major component. One review will take place during the design phase, and the second will occur before the release of the finalized component (i.e. before the component is moved from the experimental folder to the components folder).

All reviews will be performed adhering to the IEEE 1012 Standard for Software Verification and Validation for Software Design Evaluation and Source Code and Source Code Documentation Evaluation cite: ieee1012:web. Each review will be moderated by the primary developer and at least one other senior member of the OSSIE Team.

In order to improve the quality of our software, all team members are encouraged to check the changesets in the repository and independently review all recent changes committed by other team members. This practice should be performed by each team member regularly--ideally every day before work begins.

OSSIE Repository

Major projects, components, and tools must have their own folder in the repository, with accompanying trunk, branches, and tags subfolders.

Waveform components must be located in subfolders of the experimental directory during development. The component is then moved to the components folder after it has passed all of the required tests, the final review, and its documentation is complete.

OSSIE Testing

Repeatable testing is a requirement for every component developed by the OSSIE Team. It is a priority of the OSSIE team to automate testing.

For Core Framework components, the main testing tool is JTAP. Before committing changes to the framework, the respective regression tests in JTAP must be passed.

For waveform components, automatic testing using cxxTest is expected whenever possible. All test suites, test vectors, and expected result vectors must be committed into the repository as part of the component. For installation and usage of cxxTest refer to cite: cxxtest:web.

Independent Testing (Optional - dependent on available resources)

In order to improve the quality of the software developed by the OSSIE Team, it is our policy to perform all of the validation tasks independent of the development tasks. In other words, the engineer who develops a component must be different from the one who tests it.

Component developers and test developers shall collaborate during the design stages of a given component. Once the design specifications are complete, they may begin their independent efforts.





注:OSSIE Development Procedures & Policies
(原文出处,翻译整理仅供参考!)