Changeset 3183 in orxonox.OLD for orxonox/trunk/CODING-STANDARDS

Timestamp:

Dec 15, 2004, 6:12:54 PM (19 years ago)

Author:

bensch

Message:

orxonox/trunk: new CODING-STANDARDS

File:

• orxonox/trunk/CODING-STANDARDS (modified) (2 diffs)

orxonox/trunk/CODING-STANDARDS

@@ +1 @@
+CODING-STANDARTS FOR ORXONOX
+-==============--==---+++++-
+In this file it is described how a orxonox-developer should structure his code.
+Every developer has to read it and follow the rules, and orxonox will grow.
 
-
+Contents:
+---------
+1.Coding Conventions
+2.How to format your Code
+3.Example
 
 1.Coding Conventions
-2.How to format your Code
-
-1.Coding Conventions
---------------------
+====================
 ==> If you are beginning a new code-file: copy the proto_class.{cc,h}
 ==> and work with these files.
 
-a) in every code file, there has to be a GNU copyright header
-b) under the (c) header write your name as main-programmer, if
-   you are just bugfixing or extending write it under co-programmer
-c) Every function has a header with informations about it:
-/**
-   \brief <a brief description>
-   \param <parameters the function needs>
-   \param <more parameters>
+1.1.What has to be there:
+-------------------------
+  a) in every code file, there must be a GNU copyright header.
 
-   <more description>
-*/
-   This makes live easier, if we want to add a documentation.
+  b) under the (c) header write your name as main-programmer, if
+     you are just bugfixing or extending write it under co-programmer.
+
+  c) Every element of the must be documented with doxygen-tags.
+
+1.2.Doxygen Tags:
+-----------------
+Doxygen tags in general are comments inside a file, that look just a bit different.
+most of the time they extend the /* or // with a second star or a !
+
+  a) h-files: 
+   1) every h-file you want to be documented you have to tag. (tag looks like /*! \file somefile */ )
+   2) every class has to be Documented. ( //! what it does)
+   3) special variables can be documented. ( //!< wow this member is cool because )
+
+  b) cc-files:
+   1) all the methods must be documented, and all their parameters and return value must be covered.
+
+  c) look out for this: Doxygen parses preprocessor arguments,
+     so if some comments is excluded by a #ifdef, #endif 
+     doxygen will not parse it. And ther will be nothing in the docu.
 
 
 2.How to format your Code
--------------------------
+=========================
 We use the GNU conding convention (which is also used in xemacs etc.):
 
@@ -51 +69 @@
 
 
+
+
+3.Example
+=========
+3.1.Header
+----------
+A standard header has the same name as the Class it handles.
+
+someclass.h
+-----------
+/*!
+  \file someclass.h
+  \brief Some short description of the someclass
+  \todo maybe there remains something to do in this entire file
+
+  Here comes a longer description
+  this can also be longer than one line
+*/
+
+#ifndef _SOMECLASS_H
+#define _SOMECLASS_H
+
+#include <many_headers>
+#include "stdincl.h"
+
+//! short description of the class
+/**
+  \todo what remains to be done here
+
+   longer description
+*/
+class SomeClass
+{
+  private:
+   int usefull_variable;
+   int cool_variable; //!< this variable is cool, because...
+
+  protected:
+    char* someOtherMember;
+
+  public:
+   SomeClass (void);
+   ~SomeClass (void);
+   
+   int mightyFunction (char* name, int value);
+//....
+};
+
+#endif /* _SOMECLASS_H */
+
+
+
+3.2.CC-Files
+------------
+CC-files must be named the same as the .h-files they belong to.
+
+someclass.cc
+------------
+
+/* 
+   orxonox - the future of 3D-vertical-scrollers
+
+   Copyright (C) 2004 orx
+
+   This program 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 2, or (at your option)
+   any later version.
+
+   ### File Specific:
+   main-programmer: The Name of Myself
+   co-programmer: ...
+*/
+
+#include "someclass.h"
+
+
+/**
+   \brief <a brief description>
+   \todo I think you get it.
+
+   <more description>
+*/
+SomeClass::SomeClass (void)
+{
+   //constructor-stuff
+}
+
+/**
+   \brief <a brief description>
+   \todo if something is not destructed it will be here
+
+   <more description>
+*/
+~SomeClass::~SomeClass (void)
+{
+  //destroy all te allocated space of the Class
+}
+
+/**
+   \brief <a brief description>
+   \param name <what is this parameter for>
+   \param valuse <what for...>
+   \returns <what it returns>
+
+   <more description>
+*/
+int SomeClass::mightyFuncion (char* name, int value)
+{
+  this->coolVariable = value;
+  // and so on.....
+}
+
+// ...