Aslam cv specific code style

In this repository we follow the ASL coding guidelines with some modifications:

Programming style

• Don't be fancy: Aslam_cv is a library used by many people. If you want to show off weird code that exploits a specific particularity of a compiler or the c++ language try it somewhere else. The code should be efficient but also readable by humans. There is a place for SSA and inline assembly, but 99.9% of the time, a normal implementation is as efficient as a complicated one, or it just doesn't matter anyway.
• Be efficient at the appropriate time: Think about if a particular optimization just degrades readability and shows off what a great programmer you are or if it is actually improving performance.
• Watch your algorithmic complexity and memory access: On most modern machines the memory access is the limiting factor, watch memory layout, pointer indirection and loop-ordering as these are most strongly influencing performance.

Variable and parameter naming

• Prefer writing out a human understandable name and avoid abbreviations where possible.
• Strictly keep the correct mathematical notation for frames and transformations as discussed [here](Expressing frame transformations in code.). Add short comments if the single letter frame specification is not self explanatory, but do not write the full name for a frame.

Naming of variables and methods

• Name your variables s.t. other people can directly understand what is going on.

bool projection_successful = camera->Project(/*...*/)

• Methods should contain a verb s.t. it is clear what a method does:

bool UndistortImage(const cv::Mat& input_image, cv::Mat* output_image) const {
// ...
}

Commenting

• Do not comment on obvious parts of the code.
  • Don't do this:

   // Allocate an empty image.
   cv::Mat img;
   // Load the image from the file specified by file_name.
   img.load(file_name);
  

• Comment on parts of the code which are non-standard or where to document where ever a non-standard approach was taken for a non-obvious reason.
  • But do this:

  // O_DIRECT writing uses DMA and to achieve this needs the input memory to be
  // memory aligned to multiples of 4096.  See man 2 memalign for details.
  #ifdef ANDROID
  #define posix_memalign(a, b, c) (((*a) = memalign(b, c)) == NULL)
  #endif
  

Function signatures

Parameter passing

• Input values of primitive types (int, double, bool etc.) are passed by value.
• Input values of complex types (classes etc) are passed by reference to const.
• Input/Output values are passed by pointer.
• Output values are passed by pointer.

Passing shared pointers

• Input shared pointers are passed by reference to const.
• Shared pointers where the content (the object that the pointer points to) is modified are passed by value
• Shared pointers which are modified themselves are passed by pointer.

Parameter ordering

• Input, Input/Output, Output

Default values

• Do not put default values for methods. They are too often introducing bugs when parameters get reordered. Instead use overloads. Discussion

Parameter checking

• All parameters passed by pointer need to be checked for null. Use the GLog CHECK_NOTNULL(pointer); macro for raw pointers and the GLog CHECK(shared_ptr) macro for shared_ptrs.

Value Checks

Use the GLog CHECK(x) macros instead of assertions. http://google-glog.googlecode.com/svn/trunk/doc/glog.html

Unlike assert, it is not controlled by NDEBUG, so the check will be executed regardless of compilation mode.

Prefer the specific macros where possible:

CHECK_NOTNULL(some_ptr);
some_ptr->DoSomething();

CHECK_EQ(2, 1 + 1)
CHECK_EQ(std::vector<int>().size(), 0u);

CHECK(bool(1), true);

CHECK_LT(1, 2);
CHECK_NEAR(1.0, 1.0000001, 1e-4);