The CARMEN Style Guide

The Prime directive

You are not the only person who will ever have to read, understand and modify your code.

Units and Coordinates

Always represent all units in MKS. All distances are always in metres. All angles are always, always in radians.

Naming conventions

The most important naming convention is to expect that your code could be converted into a library one day. Therefore, it is important to think about global name spaces.

Memory management, system calls, and functions with side effects

Never use a system call without checking the return value. This includes any memory allocation. We have provided a function \ carmen_test_alloc that facilitates memory checking. CVS will not allow code to be committed to core CARMEN that contains a call to malloc/calloc/realloc and does not have a call to carmen_test_alloc on the subsequent line.

Wrong: char buffer[11] for a string of length 10. Why? You minimize the probability of off-by-one errors writing into memory you don't own. Memory is cheap. If you really need to create ``just-big-enough'' memory arrays because you're running out of memory, you're solving the wrong problem.


Do not initialize IPC yourself. Use carmen_initialize_ipc.

We expect that all modules will have well-defined interface libraries that relieve the user of having to worry about marshalling data.

The timestamp should also reflect the time of creation of the data, not the time the message was published. For instance, the laser message timestamp is the time the data was read from the serial port. Use the helper function carmen_get_time_ms() to generate the timestamp as a double.


Keep graphics and robot functionality in separate processes.

Notice that none of the core robot functionality (base_services, robot, navigator, localize) link against graphics libraries. This is for multiple reasons:

It increases the likelihood that your code will work on a standalone robot in the absence of a network. If your process is displaying output to a remote X window, and the network drops out, your process will wedge until the network comes back. If, however, your process is sending IPC messages to an external display process, then only the display process will wedge, not your (presumably more important) robot process.

For obvious reasons, programs like map and mapper have displays compiled in -- these programs are not intended for autonomous use on the robot.
Generated on Wed Apr 5 18:34:20 2006 for CARMEN by  doxygen 1.4.4