Opening a GitHub pull request would be the best way. Please make sure that your code follows DART conventions.
The code doesn't need to be perfect right away, feel free to post work-in-progress versions to get the discussion started.
C++ headers and sources should be contained in the same subdirectory of dart/ that matches their namespace, with the file extensions .hpp for headers and .cpp for sources.
| Style | Convention |
|---|---|
| Directories | snake_case |
| Files | PascalCase |
| Classes | PascalCase |
| Global functions | PascalCase |
| Function names | camelCase |
| Variables | snake_case |
| Indentation | two spaces |
#pragma once // Use #pragma once instead of header guards
// Use clang-format to sort the headers.
// - Includes should be at the top of the file.
// - Group headers from most specific to most general.
// - Within each group, sort the headers alphabetically.
// - Use absolute paths for the headers.
// - Use angle brackets for the headers listed in the public headers.
#include <dart/common/pointers.hpp>
#include <dart/component_name/ExampleInterface.hpp>
#include <dart/component_name/ExampleOtherInterface.hpp>
#include <3rd_party/headers.hpp>
#include <stl_headers>
#include <c_headers>
namespace dart {
namespace example {
/// Namespaces scopes should be one line each with "cuddled" braces.
DART_COMMON_MAKE_SHARED_WEAK(ExampleClass)
/// A required Doxygen comment description for this class. This can be extended
/// to include various useful details about the class, and can use the standard
/// Doxygen tag set to refer to other classes or documentation. It should use
/// the '///' style of block comment.
class ExampleClass : public ExampleInterface, public ExampleOtherInterface
{
public:
EIGEN_MAKE_ALIGNED_OPERATOR_NEW // Many classes that require Eigen will also need this macro
/// Required brief description of constructor. This will often be as simple as:
/// "Creates an instance of ExampleClass."
///
/// \param[in] foo This is an example parameter description.
/// \param[in] bar This is a longer example parameter description that needs
/// to wrap across multiple lines.
explicit ExampleClass(std::unique_ptr<util::RNG> foo,
const Eigen::Isometry3d& bar = Eigen::Isometry3d::Identity());
ExampleClass(const ExampleClass& other);
ExampleClass(ExampleClass&& other);
ExampleClass& operator=(const ExampleClass& other);
ExampleClass& operator=(ExampleClass&& other);
/// If a class should be non-copyable, it should explicitly delete the following:
ExampleClass(const ExampleClass&) = delete;
ExampleClass(ExampleClass&& other) = delete;
ExampleClass& operator=(const ExampleClass& other) = delete;
ExampleClass& operator=(ExampleClass&& other) = delete;
/// Classes should explicitly declare a default virtual destructor
/// if they do not declare one (unless marking a class as final).
virtual ~ExampleClass() = default;
/// Documentation inherited. <-- Use this comment to indicate that the docstring of the interface method applies
int exampleInterfaceFunction() const override; // <-- Always explicitly `override` interface functions without `virtual`
/// Required brief description of method.
/// \note If a method has output parameters, they should be the last
/// arguments.
///
/// \param[in] a A description of a
/// \param[in] b A description of b
/// \param[out] out A description of out
int exampleMethod(int a, int b, int* out) const;
private:
std::unique_ptr<util::RNG> m_example_member; // Member variables are prefixed with "m"
};
} // namespace example
} // namespace dart
// In certain cases, such as heavily templated code, implementations must be included
// in headers. In this case, a "detail" header should be created in the "./detail"
// subdirectory with the same name as the main header file, but an "-impl" suffix.
// Private declarations in this header can use a "detail" sub-namespace.
#include <dart/component_name/detail/ExampleClass-impl.hpp>// Includes should be at the top of the file.
// The first include in a class source file should be the matching `.hpp` header file.
// Use double quotes for 1st party headers.
#include "dart/example/ExampleClass.hpp"
// Sort from most specific to most general.
// Use angle brackets for 3rd party headers and system headers.
#include <library/headers.hpp>
#include <stl_headers>
#include "dart/example/OtherHeaders.hpp"
// Namespace nesting is preferred to "using namespace" directives.
// Namespaces scopes should be one line each with "cuddled" braces.
namespace dart {
namespace example {
// Each function is separated by an 80 column line of "=" characters.
//==============================================================================
int ExampleClass::exampleInterfaceFunction() const
{
// Use braces for all control structures, even single-line statements.
if (m_example_member) {
return 3;
}
return -1;
}
//==============================================================================
int ExampleClass::exampleMethod(int a, int b, int* out) const
{
int result = a + b;
if (out) {
*out = result;
}
return result;
}
} // namespace example
} // namespace dartDART_ENABLE_*: These are CMake options that enable/disable various features of DART. The features can be disabled if the dependencies are not available.DART_HAS_*: These are automatically defined by CMake based on the availability of the dependencies.DART_ENABLED_*: These are automatically defined by CMake based on the availability of the dependencies and the corresponding DART_ENABLE_* option.
These guidelines are based on this article. Consider looking at the full article for the details.
- General Rules
- Use a by-value
std::shared_ptras a parameter if the function surely takes the shared ownership. - Use a
const std::shared_ptr&as a parameter only if you're not sure whether or not you'll take a copy and share ownership. - Use a non-const
std::shared_ptr¶meter only to modify thestd::shared_ptr. - Use
std::unique_ptranytime you want to use astd::shared_ptrbut don't need to share ownership. - Otherwise use
Object*instead, orObject&if not nullable.
- Use a by-value
You can automatically format all DART code
using ClangFormat through
CMake. Make sure clang-format 14 is installed.
cd to/dart/root/
mkdir build
cd build
make check-format # to check the code without formatting
make format # to format the code- Use two-space indentation
- Use lowercase function names
- Use all-caps variables except when referring to target names
- Use
target_VARIABLEwhen naming target-specific variables - ALWAYS quote singleton variables (e.g.
"${MY_VARIABLE}"but not${MY_LIST_VARIABLE})
cmake_minimum_required(VERSION 3.22.1) # Always declare a minimum version in the top-level CMakeLists.txt.
project(dart) # Only declare a project name in the top-level CMakeLists.txt.
# Put in comments liberally! CMake is complicated!
if(SOME_VARIABLE)
message(STATUS "Variable was set to '${SOME_VARIABLE}'.")
endif()
# Prefer using LIST functions to SET functions when working with list variables
list(INSERT CMAKE_MODULE_PATH 0 "${PROJECT_SOURCE_DIR}/cmake") # ALWAYS quote around singleton variables
list(APPEND CMAKE_CXX_FLAGS "-std=c++11")
set(MY_INCLUDE_DIR include) # Use all-caps for variables.
find_package(SomeLibrary REQUIRED) # Use REQUIRED keyword when appropriate.
# For now, `include_directories` is necessary, but later we will switch to `target_include_directories`.
include_directories(
"${MY_INCUDE_DIR}" # This should be quoted.
)
# Complex commands should be split into one line for each semantic group (with two-space indentation).
# It is OK to put a target or output on the first line.
include_directories(SYSTEM
${SomeLibrary_INCLUDE_DIRS} # This should NOT be quoted, because it is a list.
)
add_library("${PROJECT_NAME}" SHARED # This target name is generated from a variable, so it should be quoted.
src/MySourceCode.cpp
)
# Always prefer `target_link_directories` to `link_directories` or other global functions.
target_link_libraries("${PROJECT_NAME}"
${SomeLibrary_LIBRARIES}
)
# Tests will typically be added to the end of the time from a `tests` subdirectory like the following.
enable_testing()
add_subdirectory(tests)| Name | Contributions |
|---|---|
| C. Karen Liu | project creator, multibody dynamics, constraint resolution, tutorials |
| Mike Stilman | project creator |
| Siddhartha S. Srinivasa | project advisor |
| Jeongseok Lee | project director, multibody dynamics, constraint resolution, collision detection, tutorials |
| Michael X. Grey | project director, extensive API improvements, inverse kinematics, gui::osg, tutorials |
| Tobias Kunz | former project director, motion planner |
| Sumit Jain | multibody dynamics |
| Yuting Ye | multibody dynamics, GUI |
| Michael Koval | uri, resource retriever, bug fixes |
| Ana C. Huamán Quispe | urdf parser |
| Chen Tang | collision detection |
| Matthew Dutton | build and bug fixes |
| Eric Huang | build and bug fixes |
| Pushkar Kolhe | early DART build system design |
| Saul Reynolds-Haertle | examples, bug fixes |
| Arash Rouhani | build fixes |
| Kristin Siu | integrators, bug fixes |
| Steven Peters | build improvements and fixes |
| Can Erdogan | planning, examples |
| Jie Tan | lcp solver, renderer |
| Yunfei Bai | build and bug fixes |
| Konstantinos Chatzilygeroudis | mimic joint, OSG shadows, shape deep copy, build and bug fixes |
| Sehoon Ha | early DART data structure design, pydart |
| Donny Ward | build fix |
| Andrew Price | build fix |
| Eric Tobis | build fix |
| Jonathan Martin | build fix |
| Jia Ye Li | fix typo of tutorials |
| Benjamin Chrétien | bug fix |
| Olzhas Adiyatov | bug fix |
| José Luis Rivero | build, especially for Debian |
| Jonathan Scholz | build fix |
| John Turgeson | mesh model |
| Jennifer Buehler | heightmap, bug fix |
| Dong Xu | motion blur renderer |
| Donghyun Kim | Atlas texture images |
| Aditya Vamsikrishna | bug fix |
| pchorak | bug fixes |
| acxz | doxygen warning fix |
| Addisu Taddese | bug fix in ode collision detector, slip effect on contact, velocity and position integration, constraint grouping, skeleton unsubscription fix |
| Christoph Hinze | python bindings |
| Erwin Coumans | build fix on Windows/MSVC |
| Silvio Traversaro | build fix on Windows/MSVC, vcpkg packaging |
| Martin Pecka | contact surface generalization |
You can find the complete contribution history in here.