cppunit-cvs

[Baptiste L. <bl...@us...>]

Update of /cvsroot/cppunit/cppunit2/doc
In directory sc8-pr-cvs4.sourceforge.net:/tmp/cvs-serv2344/doc

Modified Files:
	cpput.dox doxyfile.in header.html 
Added Files:
	coding_guidelines.dox 
Log Message:
- started adding coding guidelines.

--- NEW FILE: coding_guidelines.dox ---
/** \page coding_guidelines Coding Guidelines

<hr>
\section cg_naming_convention Naming convention
\subsection cg_definition Definition: Capitalized First Letter convention (camel case)
This convention is used for most naming, and will be referred to as camel case convention. 
The name is in mixed case, with the first letter of each word in upper case, 
and the other in lower case. Acronym (example: DLL = Dynamically Linked Library) 
are in upper case. Unless stated otherwise, those identifiers should not contain any 
<tt>'_'</tt>.

This convention has two main variants: first letter of the name in lower case, 
and first letter of the name in upper case. If the first letter is part of an acronym, 
then the acronym is in the same case as the first letter.

Example:

<table>
<tr><td><b>First letter in upper case</b></td><td><b>First letter in lower case</b></td></tr>
<tr><td><tt>TestCase</tt></td><td><tt>testCase</tt></td></tr>
<tr><td><tt>DLLLoader</tt></td><td><tt>dllLoader</tt></td></tr>
</table>

\subsection cg_filename File name
File name should be in lower case and File name should not contain any ‘_’. File names
should be named after the feature they provide.

File extensions: 
<tt>.cpp</tt> for C++ source file
<tt>.h/.inl</tt> for C++ headers.

Rational: avoid case issues for case sensitive filesystem, corrupting CVS repository
when attempting to change file name case on buggy client.

Example :
\code
testcase.c      // OK
testcase.h      // OK
testcase.inl    // OK
resource.c      // OK

test_case.c     // BAD
TestCase.c      // BAD
TestCase.h      // BAD
TestCase.C      // BAD
\endcode

\subsection cg_cppidentifiers C++ identifiers
<DIV class='cg_rule'>
<b>Rules:</b> no identifier must contain two underscores <tt>'__'</tt> or starts with 
a single underscore <tt>'_'</tt>.
Identifiers may only contains the following characters: 
<tt>a..z, A..Z, 0..9</tt>. The usage of <tt>'$'</tt> is forbidden.
</DIV>

Rationale: such usage of underscore is reserved by the C++ standard. 

Notes: 
- C++ compiler usually decorates identifiers using <tt>'__'</tt>, therefore using <tt>'__'</tt> 
might result in (silent) linking issues.
- run-time libraries frequently use macros starting with <tt>'_'</tt> for their implementation.

\subsection cg_macro Macro names
<DIV class='cg_rule'>
<b>Rules:</b> Macro name must be completely in upper case, with words separated by an underscore ‘_’. 
Macro name should also be prefixed with a library or application name. 
This prefix serves as namespace and help avoiding conflicts.
</DIV>

The following prefix should be used:
<table>
<tr><td><b>Library</b></td><td><b>Prefix</b><td></tr>
<tr><td>CppUnit 2</td><td>CPPUT_<td></tr>
<tr><td>CppTL (CppUnit Tool Library)</td><td>CPPTL_<td></tr>
<tr><td>JsonCpp</td><td>JSON_<td></tr>
<tr><td>OpenTest</td><td>OPENTEST_<td></tr>
</table>

Rationale: macro substitution occurs at preprocessing time without regards to namespace. 
Prefixing macro names help makes them unique and avoid clash between libraries. 
The naming conventions are such that no C++ identifier should have a name similar to 
a macro name. This conventions is widely adopted across all C++ naming conventions, 
meaning that it also help avoid conflicts with third-parties.

\subsection cg_class Class names
<DIV class='cg_rule'>
<b>Rules:</b> Class name must be in camel case, starting with an upper case letter.
</DIV>

Rationale: defined by java standard naming convention, and a widely spread C++ convention as well. 
Identifiers starting with an upper case are used to identify ‘Type’ identifiers 
(enum, class...)

Example:
\code
Test
TestCase
ExceptionGuard
\endcode

\subsection cg_attributes Class attributes
<DIV class='cg_rule'>
<b>Rules:</b> attribute names must be in camel case starting with a lower case letter 
and suffixed with an underscore <tt>'_'</tt>.
</DIV>

Rationale: defined by java standard naming convention, and a widely spread C++ convention 
as well. Identifiers starting with a lower case are used to identify ‘value’ identifiers 
(attribute, variable...)

Example:
\code
int size_;
double timeOut_;
LightTestRunner runner_;
\endcode

\subsection cg_memfn Member function names
<DIV class='cg_rule'>
<b>Rules:</b> member function names must be in camel case, starting with a lower case. 
The name should contains a verb and be structured in such a way that 
it can be read naturally.
</DIV>

Rationale: This is a widely spread convention in the Java and C++ community. 

Recommendation: when overriding virtual function, specify in which inherited class the virtual function is defined:

Example:
\code
void addChild( const std::string &parentSuiteName,
                const std::string &childSuiteName );

bool removeChild( const std::string &parentSuiteName,
                    const std::string &childSuiteName );

TestFactoryId add( const std::string &parentSuiteName,
                    const TestFactory &testFactory );

class OPENTEST_API TestRunnerServer : public RemoteMessageServer
                                    , private TestRunnerListener
{
public:
   TestRunnerServer( TestRunnerInterface &impl );

   void attachTransport( const MessageTransportPtr &transport );

public: // overridden from RemoteMessageServer
   void dispatchPendingMessages( const RemoteMessagePtr &message,
                                 MessageTransport &transport );

public: // overridden from TestRunnerListener
   virtual void testRunStarted( TestRunId testRunId );
   virtual void testRunDone( TestRunId testRunId );

   virtual void startTesting( TestPlanId testPlanId );
   virtual void doneTesting( TestPlanId testPlanId,
                             const ResultStatus &status );
private: //
	...
};
\endcode


\subsection cg_enum Enumeration type
<DIV class='cg_rule'>
<b>Rules:</b> enumeration type name must be in camel case, starting with an upper case.
</DIV>

Rationale: avoid potential clash with macro.

Example:
\code
enum ParameterRequirement
{
    noParameter,         
    optionalParameter,   
    requiredParameter,   
    oneOrMoreParameter,  
    zeroOrMoreParameter  
};
\endcode

\subsection cg_localvar Local variables and function parameters
<DIV class='cg_rule'>
<b>Rules:</b> local variable and function parameters must be in camel case, 
starting with a lower case. Name should be ‘intention revealing name’, 
that is indicating what is the use of the variable/parameter rather than 
indicating what the variable/parameter is.
</DIV>

Rationale: avoid ambiguity in declaration between type and variable name.

Example:
\code
bool 
parse( const std::string &document, 
       Value &root,
       bool collectComments = true );
\endcode

<hr>
\section cg_styleguide Style Guide

The following style should be used when writing code:
- Indent size: 3 spaces
- No tabulations, only spaces (code editor must be configured this way)
- Max line length around 95 characters.

General code layout:
- space inside braces in function call and condition
- curly brace should be aligned with keyword initiating the block statement.
- only one variable declaration per statements.
- one member initialization per line in constructor, comma aligned with colon in
  case of multiple member initializations.
- at least one line (preferably two) to separate free/member function definitions.
- return type in function definitions should be 
\code
// An example of constructor
TestCase::TestCase( const CppTL::Functor0 &setUp,
                    const CppTL::Functor0 &run,
                    const CppTL::Functor0 &tearDown,
                    const std::string &name )
   : AbstractTestCase( name )
   , setUp_( setUp )
   , run_( run )
   , tearDown_( tearDown )
{
}

// An example of member function definition
bool
Reader::readComment()
{
   Location commentBegin = current_ - 1;
   Char c = getNextChar();
   bool successful = false;
   if ( c == '*' )
      successful = readCStyleComment();
   else if ( c == '/' )
      successful = readCppStyleComment();
   if ( !successful )
      return false;

   if ( collectComments_ )
   {
      CommentPlacement placement = commentBefore;
      if ( lastValueEnd_  &&  !containsNewLine( lastValueEnd_, commentBegin ) )
      {
         if ( c != '*'  ||  !containsNewLine( commentBegin, current_ ) )
            placement = commentAfterOnSameLine;
      }

      addComment( commentBegin, current_, placement );
   }
   return true;
}
\endcode

<hr>
\section cg_guidelines Guidelines

- config.h included in all headers (may be indirectly)
- DLL macros
- Forwards all classes and typedef in forwards.h
- RAII
- standard interfaces, but CppTL::ConstString as attribute to ensure thread-safety.
- no member function template (use free function instead)
- no cast style function template, use CppTL::Type instead (link issue with VC6)
- use assertions to check precondition (or intermediate condition in complex algorithm)

*/

Index: doxyfile.in
===================================================================
RCS file: /cvsroot/cppunit/cppunit2/doc/doxyfile.in,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** doxyfile.in	2 Sep 2006 13:53:41 -0000	1.2
--- doxyfile.in	7 Sep 2006 22:45:50 -0000	1.3
***************
*** 27,31 ****
  INHERIT_DOCS           = YES
  TAB_SIZE               = 3
! ALIASES                = 
  OPTIMIZE_OUTPUT_FOR_C  = NO
  OPTIMIZE_OUTPUT_JAVA   = NO
--- 27,35 ----
  INHERIT_DOCS           = YES
  TAB_SIZE               = 3
! ALIASES                = "testCaseSetup=\link CppUT::AbstractTestCase::setUp() setUp()\endlink" \
!         "testCaseRun=\link CppUT::AbstractTestCase::run() run()\endlink" \
!         "testCaseTearDown=\link CppUT::AbstractTestCase::tearDown() tearDown()\endlink" \
!         "json_ref=<a HREF='http://www.json.org/'>JSON (JavaScript Object Notation)</a>"
! 
  OPTIMIZE_OUTPUT_FOR_C  = NO
  OPTIMIZE_OUTPUT_JAVA   = NO
***************
*** 74,78 ****
  # configuration options related to the input files
  #---------------------------------------------------------------------------
! INPUT                  = ../include/cpptl ../include/cpput ../include/json ../src/cpptl ../src/cpput ./fake_stl .
  #  ../src/opentest ../include/opentest 
  FILE_PATTERNS          = *.h *.cpp *.inl *.dox
--- 78,82 ----
  # configuration options related to the input files
  #---------------------------------------------------------------------------
! INPUT                  = custom.css ../include/cpptl ../include/cpput ../include/json ../src/cpptl ../src/cpput ./fake_stl .
  #  ../src/opentest ../include/opentest 
  FILE_PATTERNS          = *.h *.cpp *.inl *.dox
***************
*** 107,111 ****
  HTML_HEADER            = header.html
  HTML_FOOTER            = footer.html
! #HTML_STYLESHEET        = 
  #HTML_ALIGN_MEMBERS     = YES
  GENERATE_HTMLHELP      = NO
--- 111,115 ----
  HTML_HEADER            = header.html
  HTML_FOOTER            = footer.html
! HTML_STYLESHEET        = 
  #HTML_ALIGN_MEMBERS     = YES
  GENERATE_HTMLHELP      = NO

Index: cpput.dox
===================================================================
RCS file: /cvsroot/cppunit/cppunit2/doc/cpput.dox,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** cpput.dox	2 Sep 2006 22:08:48 -0000	1.5
--- cpput.dox	7 Sep 2006 22:45:50 -0000	1.6
***************
*** 3,6 ****
--- 3,7 ----
  
  \ref cpput_todo.
+ \ref coding_guidelines.
  
  \section _warning WARNING

Index: header.html
===================================================================
RCS file: /cvsroot/cppunit/cppunit2/doc/header.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** header.html	6 Mar 2006 07:46:58 -0000	1.1
--- header.html	7 Sep 2006 22:45:50 -0000	1.2
***************
*** 4,7 ****
--- 4,15 ----
  <link href="doxygen.css" rel="stylesheet" type="text/css">
  <link href="tabs.css" rel="stylesheet" type="text/css">
+ <style type='text/css'>
+ .cg_rule {
+ 	background-color:grey;
+ 	border-style:solid; 
+ 	border-width:2px;
+ 	padding-left: 0.5ex;
+ }
+ </style>
  </head><body> 
  <table width="100%">