This is an old revision of the document!


CRAM Programming Guidelines

Collaborative Development

If you're working on a package that other people are working on / are using, please try to stick to the following guidelines:

  • Always use the GIT version control system when developing
  • One commit per feature with a meaningful commit message
  • Use square brackets to annotate for which package the commit is. E.g.: ”[btr] new feature for btr package”
  • Send a pull request through GitHub, when:
    • you want somebody to review your code
    • you want your code to be tested on a different machine than yours
  • When sending pull requests always try to include a person who you'd like to review it in the comment to the request

If you want to introduce major interface changes through you code, make an announcement on the cram-developers mailing list

Development of Roslisp Packages

package.xml

Relevant documentation: Package.xml Ref

  • As a <build_depend> only specify all the rosdep keys or ROS packages that your package requires at build-time, e.g. other ROS package sources, library headers. Whereas, <run_depend> is for rosdep keys and ROS packages that your package needs at run-time, e.g. shared libraries, executables, Python modules, launch scripts. More documentation for this can be found here.
  • Use <export><deprecated /></export> to tag deprecated packages
  • The license for all CRAM code should be BSD / Public Domain
  • Put links to github into the <url type=“bugtracker”> and <url type=“repository”> tags

my-package-name.asd files

  • Put it into the root of your source directory, no need for symbolic links and asdf directories
  • Always explicitly specify dependencies on all the Lisp packages, symbols of which you use in your code (even if the dependency is transitive and is automatically added by other packages that you depend on).

Coding Style

Lisp

  • Pay attention to the indentation!!!
  • Try not to exceed 80 symbols in width in your code
  • Lisp names (variables, classes, methods, packages) are all lowercase with dashes in between: my-awesome-lisp-variable
  • Do you usually get that feeling that something is underdocumented? :) Think about that when writing your own code. (not that the author of this guideline always sticks to this particular rule, unfortunately…)
  • Try not to use too many packages in your package.lisp. Instead, specify package namespaces explicitly in your code, e.g. cl-transforms:x instead of x. That way code is more readable.
  • Don't use cl-tf if you actually want cl-transforms. The difference is:
    • cl-transforms defines datatypes such as pose and transform and their utility functions, such as angle-between-quaternions.
    • cl-transforms-stamped defines datatypes of pose-stamped and transforms-stamped. So once you need a frame header, use cl-transforms-stamped.
    • cl-tf defines the transform listener library, so if you need to do lookup-transform, use cl-tf.
    • cl-tf2 is the equivalent of cl-tf only with an alternative implementation based on the buffer_server from tf2_ros package.

Ros-related

  • ROS packages' names are usually lowercase with underscores in between: my_awesome_ros_package.

Lisp Programming

Todo: Some Lisp patterns and stuff would be nice, like tail recursive functions and optimization flags, making sure the functions have no side effects, etcetc…