Coding

From Yade

(Redirected from Coding guidelines)


Documentation

All your classes should be documented using Doxygen format.

  • Overview of class should specify its typical usage and explain algorithms used
  • method and data memeber documentation should document all non-obvious features
  • If your algorithm is involved, contains complicated mathematical formulas or makes part of a bigger whole, create a dedicated page on the wiki in and put link into the source.

Header conventions

Your header file should contain multiple inclusion guard, like this:

#ifndef MYPLUGIN_HPP
#define MYPLUGIN_HPP
 
/* code here */

#endif

All headers from Yade that you include should be in the form

// good, will find the right file:
#include<yade/pkg-common/AABB.hpp> 

// this is OK for your own files
#include"myPlugin.hpp"

Not in form

// this is BAD!!!
#include"../../../common/DataClass/BoundingVolume/AABB.hpp"

Multi-class plugins

You may want to have multiple classes in one plugin file. It is convenient if these classes are tightly related function-wise or you don't want to have too many smallish files around. To do this, you must define special symbol in the .cpp file (if your plugin is composed of multiple .cpp files, it must be in exactly one (any) of them):

const char* yadePluginClasses[]={
	"myClass1",
	"myClass1b",
	"myClass3",
	NULL /*sentinel*/
};

If plugin loader find this symbol in your plugin, it will know what classes it defines. Otherwise, the name of class you define must be the same as that of the compile plugin, i.e. myPlugin.

Compiler warnings

Your code should compile without any (zero) warnings (including unsigned-to-signed comparisons and unused variables).

Directory structure

directory description
|-- core yade-core contains abstractions underlying various methods of physical simulation.
|-- debian debian package build system
|-- doc Documentation (in early stages of creation)
|-- examples some example input files for yade filegenerators.
|-- extra Extra packages
| |-- clump Clump support for yade.
| |-- spherical-dem-simulator a DEM simulator package written only to compare the speed of different implementation.
| `-- tetra Tetrahedron simulation package
|-- gui Interfaces available for interaction with yade. Command Line Interface is inside yade-core
| |-- cmd Python scripting interface for yade.
| `-- qt3 Qt GUI interface for yade.
|-- lib Libraries used by yade. The general goal is to remove them and switch to libraries with better official support like boost
| |-- base logging facility and wildmagic 3 (Wm3) call wrappers
| |-- computational-geometry Computational geometry library contains formulas for intersections, distances between geometrical objects and generating polyhedron with marching cubes.
| |-- factory Factory is a C++ wrapper for dynamic linking loader ( eg. dlopen() ). It handles loading and unloading plugins given their className as a string, after which plug-in file on the hard drive is named.
| |-- loki a C++ library of generic design patterns, for now is little different than libloki, but we will fix it soon by removing it.
| |-- miniWm3 Yade mini wm3 math library is a very small subset of Magic Software (wild magic 3) and provides quaternion, vector and small matrices calculus, in form optimized for 3D operations. Uses LGPL license.
| |-- multimethods The Multimethod C++ OO design pattern allows dispatching of a function call depending on types of multiple objects. Up to 4D can work (we use 2D currently), adding more than 4D is easy (but rarely needed).
| |-- opengl Wraps GL/gl.h, GL/glut.h with C++ templates, to automatically choose between glVertex3dv, glVertex3fv and the like. And a FPS tracking window in gl.
| |-- serialization serialization library more focused on easily readable xml than boost::serialization, with random access to serialized elements (not on the fly). To be removed soon as we switch to boost::serialization
| |-- serialization-bin binary format serialization handler
| |-- serialization-qt QT GUI serialization handler, de/serializes data to/from qt dialog boxes
| `-- serialization-xml xml format serialization handler
|-- pkg packages extending upon the base of yade core
| |-- common Plugins used commonly in yade
| |-- dem Discrete Element Method for yade, Open DEM
| |-- fem Finite Element Method for yade, Open FEM
| |-- lattice Lattice Geometrical Model for fracture propagation, Open LGM
| |-- mass-spring Mass Spring Model for yade, Open MM
| `-- realtime-rigidbody Realtime Rigidbody simulation model for yade, Open RRB (weird names, huh?)
`-- scripts bash and python scripts used in development