Contribution and Coding Style Guide Bullet Physics Library

 

Contribution and Coding Style Guide

 

Bullet Physics Library

 

///Authors: Erwin Coumans and John McCutchan

///Initial version April 4, 2008

///Updated June 3, 2010: Clarified some guidelines

///Updated April 23, 2015: Add more guidelines

///Update March 2017: Explain bracket use

///http://bulletphysics.org

 

See also our clang-format file. You can use the following command to format a file:

 

clang-format -style=file -i path/to/file.cpp

General guidelines:

 

1. Make sure you are legally allowed to make a contribution under the zlib license

2. The Zlib license header goes at the top of each source file, with appropriate copyright notice.

3. After a pull request, check the appveyor and travis status on http://github.com/bulletphysics/bullet3

4. One class per header file, smaller structures can be combined in a single file.

5. No use of global variables, singletons, namespaces (except some examples code)

6. Prefer implementation in a CPP file instead of a header file.

7. Use only C++2003, (no C++11 yet).

8. No use of exception handling, no RTTI.

9. Use tabs instead of multiple spaces. 

10. Use Doxygen-style comments.

11. Don't use STL. Bullet provides btAlignedObjectArray to replace std::vector

12. Make sure memory allocation in the core SDK goes through the central memory allocator

13. No use of third-party libraries such as BOOST and so on.

14. Don't include #include <stdio.h> or similar include files in the core SDK. In demos and examples it is ok.

15. Try to use const when possible

16. Make sure to comment out printf, used while debugging

17. Member variables start with m_ and go first at the top of the class declaration

18. Avoid circular dependencies of classes.

19. Avoid multiple inheritance.

20. Use forward declaration whenever possible instead of including other header files

21. A header file should compile as-is without requiring other header files to be included first

22. Use btScalar instead of float/double so that Bullet can be compiled as double/single precision

23. Make sure the code compiles on 32bit and 64bit platforms in single and double precision.

24. Use CamelCase naming, class names start with bt prefix, variable names start with lower case

25. Opening brackets start on the next line. Always use brackets, even for one-line if statements.

Please review the following example class implementation and declaration (header file)

 

//Example source file for a class.

--------------------------------------------------------------------------------

/*

Bullet Continuous Collision Detection and Physics Library

Copyright (c) 2003-2015 Erwin Coumans http://bulletphysics.org

This software is provided 'as-is', without any express or implied warranty.

In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,

including commercial applications, and to alter it and redistribute it freely,

subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

*/

 

///Always include the own class header file first.

///A header file should not rely on any other include files.

///Assume Bullet/src as base include path.

///Don't use relative paths in include file names.

///Don't include the public btBulletDynamicsCommon.h in internal implementation

 

#include "btExampleCodingStyleClass.h"

#include "BulletDynamics/Dynamics/btRigidBody.h"

btExampleCodingStyleClass::btExampleCodingStyleClass()

:m_somePrivateMember(0)

{

}

btExampleCodingStyleClass::~btExampleCodingStyleClass()

{

}

void btExampleCodingStyleClass::someFunctionName(btRigidBody* body)

{

int i;

for (i=0;i<m_somePrivateMember;i++)

{

body->getLinearVelocity();

}

//always use brackets, even for one-liners!

if (i==2)

{

body->getLinearVelocity();

}

}

 

///Example header file for a class.

------------------------------------------------------------------------------

/*

Bullet Continuous Collision Detection and Physics Library

Copyright (c) 2003-2015 Erwin Coumans http://bulletphysics.org

This software is provided 'as-is', without any express or implied warranty.

In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,

including commercial applications, and to alter it and redistribute it freely,

subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

*/

///

/// Author section: this file was created/modified by FirstName LastName

///

#ifndef _BT_EXAMPLE_CODING_STYLE_CLASS

#define _BT_EXAMPLE_CODING_STYLE_CLASS

#include "LinearMath/btScalar.h"

/// Avoid including headerfiles if possible and use forward declarations instead.

class btRigidBody;

///This btExampleCodingStyleClass is an example to demonstrate coding style.

///It starts with 3 slashes, to help Doxygen.

///Explanation/documentation can be multiline.

///Avoid using /* */ comments in general, except for the license header.

class btExampleCodingStyleClass

{

int m_somePrivateMember;

  btAlignedObjectArray<btRigidBody*> m_bodies;

protected:

btScalar m_someProtectedMember;

public:

btExampleCodingStyleClass();

virtual ~btExampleCodingStyleClass();

///someFunction explanation and comments start with 3 slashes, to help Doxygen

///function names start with lower case

///multiple concatenated words are capitalized

void someFunctionName(btRigidBody* body);

///if the getMember function becomes larger, please move it to the .cpp file

const int getMember() const

{

return m_somePrivateMember;

}

};

#endif //_BT_EXAMPLE_CODING_STYLE_CLASS