Versions Compared

Old Version 1

changes.mady.by.user Anonymous

Saved on

compared with

New Version Current

changes.mady.by.user Anonymous

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info

Note: This page is under construction and soon will move to GitHub.

...

If the “copy stuff” part consists only of assignments that work for self assignment, then you can get away without the test, but unless you’ve thought it through carefully you should just get in the habit of putting in the test.

Documenting your Code

Doxygen only looks in your .h files. It does not generate documentation from cpp files. Thus comments in .cpp files don't need to follow doxygen formatting, and in fact they should not because it is confusing and makes it look like there is API documentation when there isn't. You should mostly use "//"-style comments in .cpp files, and be sure you are addressing your comments to the right audience -- no doxygen reader will ever see them.

Read more about doxygen on this page: Guide to Building Doxygen

Tab Settings

Please be sure that your IDE (code editor) is set to replace tabs with four spaces. You should never allow tab characters to get into your code. They will look great to you, but most other people will see your code as randomly formatted.

If you use Visual Studio, goto Tools:Options:Text Editor:C/C++/Tabs, set tab size=indent size=4, and check the "Insert spaces" button.

Renaming Classes in the OpenSim API

Sometimes it makes sense to change the name of a class in OpenSim because the name is confusing or doesn't reflect the desired function. This seemingly innocent, and usually desirable refactoring, has some side-effects that API developers should be aware of so that changes do not break working functionality.

1. Deserialization: The code that reads objects from XML files keys on the String representing class name to create corresponding objects (e.g. "PinJoint" class shows in XML as <PinJoint>). If you change the name of PinJoint (e.g. to MyPinJoint) you need to make sure old models that have the tag <PinJoint> still work. Normally this is captured by test cases. If you decide to make the change, you'll have to edit the file "RegisterTypes_osimSimulation.cpp" and add the line Object::renameType("PinJoint", "MyPinJoint"), so that the deserialization code knows how to handle the XML tag.

2. Swig wrapping and GUI: Most API users don't build the GUI, however they should continue to build the JavaWrapping to make sure changes on the C++ side do not cause serious problems downstream to either the GUI or scripts that we'll be distributing that utilize the Java wrapping. The mechanics for this procedure are as follows:

- Turn on JavaWrapping in CMake.  You have to have Swig and Java installed.
- Build JavaWrap project to run SWIG (http://www.swig.org/, version 2.0.4)
- Run test case testContext which ends up simulating a few GUI calls.

If a class is not included in the wrapping interface file ("OpenSim/Java/swig/javaWrapOpenSim.i) then the class is likely not used by the GUI and so is safe to change, otherwise please consult with GUI developers first before renaming.

Naming Conventions

Please follow the convention that property names use “lower_case_with_underscores” as their names, while object types use “CamelCaseUpAndDownWithoutUnderscores”. That ensures no conflicts with XML tag names and makes it easy to tell a property name from an object name.

Other C++ Coding Style Suggestions

Throw and return are not functions

...

Of course in cases where you actually need the pre- or post-value for something, you should use the appropriate operator. 

Place “*” and “&” with the type, not the variable

...

Code Block
languagecpp
/*YES*/ f(int I, string& name, char* something);

/*NO*/ f(int I, string &name, char *something);

Removing Methods

When cleaning up classes and removing methods, if you decide to remove a method then it's necessary to remove both the prototype from the header and the implementation from the cpp file (if any). While C++ doesn't complain, leaving the prototype in the header file with no implementation anywhere causes problems for wrapping. Swig runs only on the headers and has no way of knowing if there's an implementation or not. Since the methods end up being exported, they then have to be resolved at compile time of the osimJavaJNI project.