oofem-wiki

User Tools

Site Tools

Trace:
coding-conventions

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
coding-conventions [2009/06/17 13:37] – added link to doc++ bpcoding-conventions [2017/11/24 16:45] (current) – Add4d Documentation & Testing, updated Checks before commiting bp
Line 1: Line 1:
 +=====Coding standard=====
 ==== Naming conventions ==== ==== Naming conventions ====
  
Line 40: Line 41:
  
 ==== Using comments to document the code ==== ==== Using comments to document the code ====
 +OOFEM uses [[http://www.stack.nl/~dimitri/doxygen/|Doxygen]] documentation system to automatically generate the reference manual directly from the OOFEM header files. By placing comments in a few strategic places a complete reference manual, including graphics, can be generated. You will typically want to do so for your header files only.
  
-OOFEM uses [[http://docpp.sourceforge.net/|DOC++]] documentation system to automatically generate the reference manual directly from the OOFEM header files. By placing comments in a few strategic places a complete reference manual, including graphics, can be generated. You will typically want to do so for your header files only.+If you are overloading methods from another class, you should **leave the documentation empty** and make sure the parameters are named exactly the same. Only write a new documentation field if you have something new to add specifically to the implemented methods.
  
-In general, a special comments should be added straigh before each function, variable, class, define, etc. you wish to document. The simplest way is to  add a simple DOC++ comment with a short documentation string for the entry, e.g.:+In general, a special comments should be added straight before each function, variable, class, define, etc. you wish to document. The simplest way is to  add a simple comment with a short documentation string for the entry, e.g.: 
 +<code> 
 +/// Array storing nodal coordinates. 
 +FloatArray coordinates;
  
-  /// Array storing nodal coordinates. +/// Description of enumeration 
-  FloatArray coordinates;+enum SomeEnum { 
 +    SE_First,   ///< Description of first. 
 +    SE_Second,  ///< Description of second. 
 +    SE_Third,   ///< Description of third. 
 +} 
 +</code>
  
-If you intend to write more than one line of documentation, succeed this line with a comment like /** .... */ and put the long documentation text in place of ``...''. For example: +If you intend to write more than one line of documentation, succeed this line with a comment like %%/** .... */%% and put the long documentation text in place of ``...''. For example:
- +
-  /** +
-    * Triplet defining the local coordinate system in node. +
-    * Value at position (i,j) represents angle between e'(i) and e(j), +
-    * where e' is base vector of local coordinate system and e is +
-    * base vector of global c.s. +
-    */ +
-   FloatMatrix localCoordinateSystem;+
  
 +<code>
 +/**
 + * Triplet defining the local coordinate system in node.
 + * Value at position (i,j) represents angle between e'(i) and e(j),
 + * where e' is base vector of local coordinate system and e is
 + * base vector of global c.s.
 + */
 + FloatMatrix localCoordinateSystem;
 +</code>
  
-DOC++ automatically imposes a hierarchical stucture to the manual entries for classes, structs, unions, enums and interfaces, in that it organizes members of such as sub-entries. If you need to group manual entries, you may do so with the construction:+Doxygen automatically imposes a hierarchical stucture to the manual entries for classes, structs, unions, enums and interfaces, in that it organizes members of such as sub-entries. If you need to group manual entries, you may do so with the construction:
  
-  /**@name <name for the group> +<code> 
-   *  <documentation for the group> +/** 
-   */ + * @name <name for the group> 
-  //@{+ * <documentation for the group> 
 + */ 
 +///@{
     <other manual entries>     <other manual entries>
-  //@}+///@} 
 +</code>
  
 This will create an entry with the specified name, that contains all <other manual entries> as sub entries. Note, however, that class members are automatically set as sub entries of the class's manual entry.  This will create an entry with the specified name, that contains all <other manual entries> as sub entries. Note, however, that class members are automatically set as sub entries of the class's manual entry. 
Line 72: Line 86:
 To document a function or a method of a class, describe the working and usage of the member function, as well as the individual parameters and return values. For example: To document a function or a method of a class, describe the working and usage of the member function, as well as the individual parameters and return values. For example:
 <code> <code>
- /** +/** 
-  * Class implementing node in finite element mesh. Node posses degrees of freedom. + * Class implementing node in finite element mesh. Node posses degrees of freedom. 
-  * Node is atribute of few elements and it is managed by domain. + * Node is atribute of few elements and it is managed by domain. 
-  * Node manages its positon in space, and optional local coordinate system. + * Node manages its positon in space, and optional local coordinate system. 
-  * By default, global coordinate system is assumed in each node. + * By default, global coordinate system is assumed in each node. 
-  */ + */ 
-  class Node : public DofManager { +class Node : public DofManager 
-  +{ 
- +public: 
-   /** Computes the load vector of receiver in given time. +    /**  
-     *  @param answer load vector. +     * Computes the load vector of receiver in given time. 
-     *  @param stepN time step when answer is computed. +     * @param answer Load vector. 
-     *  @param mode determines response mode.+     * @param stepN Time step when answer is computed. 
 +     * @param mode Determines response mode.
      */      */
-    virtual void         computeLoadVectorAt(FloatArray &answer, TimeStep *stepN, ValueModeType mode); +    virtual void computeLoadVectorAt(FloatArray &answer, TimeStep *stepN, ValueModeType mode); 
-  }+}
 </code> </code>
  
-==== Source file layout ==== +Again, Doxygen will inherit documentation from super classes, so do not add comments unless something specific needs to be said for the implementing routine. Be sure to document all variables and return value, even trivial ones, to avoid reporting errors when generating the documentation. Currently, OOFEM contains quite a large number of errors in the documentation and a convenient way to list all these errors is to separate the stderr output with the terminal command; 
- +<code> 
-Each source file, header or implementation file starts with a Subversion identification line and an author line, e.g.: + doxygen doc/refman/doxygen.cfg 2> dox_errors.txt 
- +</code>
-  /* $Id$ */+
  
 === Header file layout === === Header file layout ===
Line 100: Line 114:
 Each header file has the following layout: Each header file has the following layout:
  
-    * Subversion identification line 
     * Copyright notice     * Copyright notice
     * Inclusion protection macro     * Inclusion protection macro
     * Headers file includes     * Headers file includes
     * Forward declarations     * Forward declarations
-    * Actual class definition with DOC++ comments+    * Actual class definition with doxygen comments
  
 For a typical example see element.h. For a typical example see element.h.
Line 111: Line 124:
 Each implementation file has the following layout: Each implementation file has the following layout:
  
-    * Subversion identification line 
     * Copyright notice     * Copyright notice
     * Header file includes     * Header file includes
Line 124: Line 136:
 uncrustify -c oofem_dir/uncrustify.cfg --replace mysource.C uncrustify -c oofem_dir/uncrustify.cfg --replace mysource.C
 </code> </code>
 +===== Documentation and Testing =====
 +OOFEM aims to be high quality software and as a such it must be accompanied by high quality, up to date documentation. Also internal tests and benchmarks are absolutely necessary to ensure continuous software quality  .
 +  * The new functionality (elements, material models, etc.) will be only accepted if relevant documentation will be provided, in particular the oofem manuals should describe the new functionality
 +  * The new functionality will be only accepted if internal tests will be developed and documented. See existing tests in oofem distribution (tests directory), and [[http://www.oofem.org/resources/doc/extractorInput/html/extractorInput.html|Extractor Specification]]
 +
 +===== Checks before committing =====
 +  * For new work, commit only when some stage of implementation is reached and code is already useful. Do not use svn repository as daily backup tool for your files, that you are developing for several weeks.
 +  * Test your implementation before committing. Run at least oofem basic tests and check the results: <code>
 +cd targets/your_target_name; make tests
 +less test_results
 +</code>
 +  * Check if documentation is updated as well (includes not only doc++ comments, but also oofem documentation, that can be affected). Making it later usually means never.
 +  * Make sure that new functionality comes with internal tests.
 +  * Please compile your sources with "-Wall", which will enable all the compiler warnings. Check compiler messages and clean up the code.  
 +  * Reformat your code using uncrustify tool
 +
 +
 +
  
coding-conventions.1245238623.txt.gz · Last modified: 2009/06/17 13:37 by bp