Conventions

Naming conventions for MoveIt! libraries and files.

Where possible these conventions aim to be a superset of the ROS conventions at
 * Topic and Node naming
 * Catkin directory layout
 * ROS C++ code style guide

=Refactor Plan= We plan to refactor the MoveIt! code to follow these "rules". The rules are a work in progress...

RULE-B Packages and Namespaces
Within the moveit_core repo there will be several packages. Each package will exist in a subdirectory of the moveit_core toplevel repo directory, where the subdirectory name matches the package name.


 * Package name will be moveit_&lt;something&gt;
 * Files and directories in each package will look like this:
 * moveit/moveit_ /package.xml
 * moveit/moveit_ /CMakeLists.txt
 * moveit/moveit_ /include/moveit_ / - contains all headers exposed to other packages
 * suggestion from isucan: we should also allow moveit/moveit_ /include/moveit_ / / subfolders.
 * moveit/moveit_ /src - contains all source files and internal headers
 * moveit/moveit_ /package.xml
 * moveit/moveit_ /package.xml
 * Everything in the package is in the same namespace: moveit_&lt;something&gt;

These options are not encouraged, but they are allowed:
 * optionally there can be additional namespaces inside the moveit_&lt;something&gt; namespace.
 * optionally there can be subdirectories in the src directory, but this is discouraged.

Here is a breakdown of packages we have now and proposed new names:

For backwards compatibility we will create namespace aliases. Here are the existing namespaces in MoveIt!:

NAMESPACE ALIASES

Comments
* (1) one could have a "using namespace moveit;" in some .cpp file and then namespaces are simpler (e.g, core::whatever instead of moveit_core::whatever), and * (2) it is nice to have one single top-level namespace for everything in moveit.
 * Ioan: I would rather have the namespaces be one global namespace (moveit) and then each package have its own namespace. This means that things will always be in moveit:: instead of moveit_ . There is no technical reason for this, I am just thinking that:
 * Ioan: In the directory structure, I think we should encourage the use of subfolders in pkg/include/ and pkg/src/. This will make things easier to understand from a high level, when looking at the code structure. Instead of seeing 50+ header files in moveit_core/include, a developer will see fewer directories, each grouping header files in some way. The fact that planning_scene/ has just planning_scene.h means (to me) that there are no other headers that I need to include if I want to use a PlanningScene -related functionality. It is also likely the number of header files will grow significantly and removing hierarchy now will hurt us in the long run. The only downside I see is extra typing when adding #include directives;

RULE-C Class Names

 * Each namespace-scope class exposed outside the package (e.g. moveit_mypackage::MyClass) has its own header file with a filename matching the class name, but lowercase (e.g. my_class.h).
 * Important internal classes should have their own header file (in src/) with a filename matching the class name, but lowercase.
 * Each class with its own header file has a corresponding .cpp file of the same basename defining at least the constructors and destructors (e.g. my_class.cpp). If needed, large classes can have additional .cpp files, and those files will have a basename matching the class name plus an underscore and additional words (e.g. my_class_transforms.cpp).  Exception: if a class is entirely defined in the header file then no .cpp file is necessary.
 * a node (or other program) should have a .cpp filename that matches the name of the executable and the node type.
 * Try not to include the package name (aka namespace name) in the name of the class.

GUIDELINE: Try to name classes within MoveIt! uniquely. This makes things more clear and easier to find. Do not do this by simply prepending the namespace name to the name of the class. In some cases having 2 different classes with the same name, each in its own package, is the clearest way to do something; but try to avoid this if possible.

RULE-D Sourcefiles and Libraries

 * Generally a package should only have a single library or a single node. Sometimes it makes sense to have one or more nodes in the same package as a library and this is OK.
 * Multiple libraries in a package are discouraged unless some of the libraries are plugins. Several plugin libraries in a single package (possibly accompanying a library which uses the plugins) are fine.
 * Generally source files should all live in the src directory and not a subdirectory. Subdirectories in the src dir are OK in some circumstances. If a library or node only incorporates a single source file then that source file should never be in its own subdirectory.

= History, old comments, rationale =

Repos comments

 * Ioan: I think there should be only 2 repos. The first one as you suggest (moveit), and the second one will be just moveit_robots. In moveit_robots we can have subfolders for different robots. One will be for pr2, which is where moveit_pr2 will go.