The following rules can be checked automatically to a certain extent using a style checker based upon the Google-Code-Style-Guidecpplint tool. You may execute it via the stylecheck target
Header-files must end with .h.
Source-files must end with .cpp.
Header-files having inline implementation end still with .h since it may change and we don't want to rename all include stmts then.
For each class there is exactly one header- and one source-file.
A filename is identical with the corresponding classname extended by its filetypesuffix.
Never include .cpp files.
Module directories start in lower case without leading W for OpenWalnut and follow then CamelCase
There are no multiline comments which aren't doxygen comments (which starts with /**). We forbid e.g.:
/* * INVALID comment*/
Each file contains a comment-header for several information, at the moment we want it to look like this:
//---------------------------------------------------------------------------//// Project: OpenWalnut ( http://www.openwalnut.org )//// Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS// For more information see http://www.openwalnut.org/copying//// This file is part of OpenWalnut.//// OpenWalnut is free software: you can redistribute it and/or modify// it under the terms of the GNU Lesser General Public License as published by// the Free Software Foundation, either version 3 of the License, or// (at your option) any later version.//// OpenWalnut 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 Lesser General Public License for more details.//// You should have received a copy of the GNU Lesser General Public License// along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.////---------------------------------------------------------------------------
The phrase // should be used for commenting except for doxygen-comments.
ToDo comments must look like this:
// TODO(username): Disable this when #313 is fixed
For each function (also not auto documented derived constructors, overloaded functions should be auto documented) there exists a short description (detailed if needed) directly in front of its declaration or definition in the header file. The tool doxygen creates a documentation from these descriptions. Such a description has the following form:
/*** fill in documentation here* \exception (exceptionname description of exception)|nothing* \param parameter1 information about parameter1* \param parameterN information about parameterN* \tparam param1_T information about template parameter 1* \tparam paramN_T information about template parameter N* \retval return parameter descr. of param. used to return sth.* \return nothing or return value specification*/
You can produce a nice html documentation with doxygen by calling make docs using your preferred shell when you are located in the base directory.
State the intention of each code passage that is not fool-proof through a comment. Same stands for variables/pointers etc.
When using names containing more than one word, we use CamelCase.
Names never start with a _.
Names permit conclusions on their meaning and they are pragmatic in their length.
Local variable names starts with a lower case letter
Member variables always start with the prefix: m_ and carry on like local variable names (starting with a lower case letter)
starts with a W followed by an upper case letter. The upper case W indicates that this is a Open*W*alnut class name.
Module classes don't contain the phrase Module instead they start with the prefix WM
should have the same name as the Module classes except the extension or file suffix should be .xpm instead of .cpp.
The public, protected and private labels are stated in this order and aren't indented
There are no implementations of methods in the class definition, except in template classes and if the method is inline.
If the member function is inline, be sure it is very short, since otherwise it may bloat the code. Also take care that inline member functions are defined outside the class but inside the header (the reason to do so, was that then the class interface is much more readable):
Member functions that do not change objects are always declared as const
Classes with virtual methods have a virtual destructor
Variables are declared with a minimal scope.
Pointers to local variables must not be returned.
All rules from the Variable section apply also to this section too
Never specify public member variables.
For each member variable that is needed outside of this class, getter and setter member functions exists and have the prefix get or set in conjunction with the name of the member variable starting with a capital letter, e.g.: getFooBar().
The only exception from this rule are getters for boolean member variables. They have to have the prefix is, e.g.: isEnabled().
Should have at least a brief doxygen description.
Avoid functions with many (~5) arguments!
Each functions should fit almost on a screen. Avoid long and complex functions!
Use const references when dealing with large data structures!
The semantic has to stay the same for overloaded operators.
Use the argument type and name when prototyping functions!
Every function has an explicit return type (void if necessary).
All rules from the Function section apply also to this section too
If a method returns some extra data in arguments then these are the first arguments of the method
Arguments that don't change have always a const modifier
The name of the function and the return type stay in the same line
The arguments can be distributed if necessary on several lines; the new line begins by a character behind the column of the opening bracket that the argument list initiates: