Information

Documentation

Get OpenRDK at SourceForge.net. Fast, secure and Free Open Source software downloads

edit SideBar

Conventions and coding style

Your are strongly asked to learn the conventions (cough cough... rules) and to respect them. The use of them from all of us will allow to read and understand the code and structure of the applications. Moreover, some conventions used in OpenRDK core will let you understand immediately the behavior of a function. Of course, you are free to use or not use the advices in the "Coding style" paragraph (instead, you are required to follow them if you write code for the OpenRDK framework itself).

Units of measurements

In order to avoid a mess and unnecessary conversion, in OpenRDK there exist only these units of measurements: meters, seconds, kilograms, radians, celsius degrees. Of course you can use whatever fancy unit of measurement for fancy quantities (e.g., eV, lumen, etc.), but for the quantities measured by the units of measurements above, you are asked to use only those ones. This means that every length should be measured in meters, every weight in kilograms, every time in seconds, etc.

If you get some quantity from outside OpenRDK, that is measured in different units of measurements (i.e., centimeters instead of meters), you should convert that immediately while entering in OpenRDK and convert it in other ways (i.e., parsec) only a moment before exporting it to an application outside the OpenRDK.

Radians are an exception, in the sense that in the code you should always have radians, but for visualization purposes (or configuration files), they are written in degrees for ease of understanding (but, again, they are translated in degrees just a moment before being displayed, and converted in radians as soon as they are read from a configuration file).

Property names

You can use "subdirectories" in the property names, in order to have a more readable repository. Some widely used "subdirectories" of the modules are:

  • in/: here you should put all the inputs of the module
  • out/: here you put the module outputs
  • cmds/: here you can put with booleans that acts as buttons (trigger some module procedure); I wrote cmds, NOT cmd!!!!
  • params/: usually for some module that is very rich of parameters, you usually want to make subdirectory of this.

For consistency, the following is important also if you want to use your own coding style in your project. All properties in the repository must have a name that:

  • is in camel case (Java-like)
  • begins with a lowercase letter

So these are legal names:

  • myLittleProperty
  • foo/bar
  • params/maxSpeed
  • params/numCycles
  • oneVeryLong/propertyName/withMultiple/subdirectories

These are not:

  • MyLittleProperty
  • foo/Bar
  • params/max_speed
  • oneVeryLong/Property_Name/with multiple subdirectories

OpenRDK reference system

In the following picture, you can see how the world reference system and the image that represents a metric grid map (RMapImage) are related. Consider (this can be different) that the robot is in world pose (0, 0, 0), in this way, its face (and thus its own x axis) is pointing towards the x axis of the world.

A map-image, in OpenRDK is an image (i.e., a grid of pixels), referenced in the world. In particular, the x and y fields of an RMapImage are the (x,y) pose in the world of the (0,0) pixel of the image. Moreover, in order to specify the resolution, you also need to set the realWidth field of RMapImage, that is the width (i.e., along the x axis of the image) in world measure (i.e., meters). So you can have an image that is 100 pixels wide (i.e., RMapImage::image::getWidth() is 100) and 5 meters wide (i.e., RMapImage::getRealWidth() is 5.0).

Finally, look at how the x and y coordinates of the world and of the image increase and decrease with respect to each other: when world x increases, the pixel x coordinate (also called "column" in a matrix) also increases, when world y increases, the pixel y coordinate (also called "row" in a matrix) decreases.

Objects passed by pointer

Inside many functions, objects passed by a pointer. The convention is that if the pointer is passed to constant object, the objetct property keeps remaining to the caller (and it could not be differently). Though, if the pointer is not to a constant object, the object's ownership passes always to the called function.

For example:

  void Session::queuePush(CUrl url, RDK2::Object* obj);

in this case, whichever object inserted in the queue will become property of the queue (that is: you should not delete that object nor keeping the pointer).

Passing pointers to session

When a function takes a pointer to session as parameter, then that session must have been already started (i.e., session->start()). In order to make errors easier to find, the called function could implement a block like the following. This will add extra information to the exceptions messages.

  void myFunction(Session* session)
  {
    // session was already started
    SESSION_TRY(session)
      // ... function body here
    SESSION_CATCH_RETHROW(session)
  }

Coding style

Although you are free to use whatever coding style in your own project, you are required to follow these rules if you are contributing to the OpenRDK. Moreover, you should also follow the rules for property names.

  • Classes name are in CamelCase, beginning with capital letter (Java style).
  • Attributes, variables and methods should be also likeInJavaStyle, starting with a lower case letter.
  • Constants should be ALL_UPPERCASE. Declare them inside classes to avoid name conflicts.
  • Indentation must be done with TABs, not spaces.

All variable names, comments, etc. must be in English.

If you find bugs or parts that need to be worked on, add a comment saying "FIXME" or "XXX". In this way, weak parts are much easier to spot.

© 2004-2009 RoCoCo Laboratory Powered by PmWiki
Edit - History - Printable View - Recent Changes - Search
Page last modified on January 19, 2009, at 01:32 PM