Programming guidelines

From Navit's Wiki
Revision as of 13:27, 30 September 2011 by Cp15 (talk | contribs)
Jump to: navigation, search

Coding Style

  • Intention with tabs
  • 8 characters per tab
  • K&R style
  • Function name at line start

indent usage:

   indent --procnames-start-lines --k-and-r-style --indent-level 8

C Standard

C95. That means:

  • No inline declarations of variables

Instead of

{
   do_something();
   int a=do_something_else();
}

use

{
   int a;
   do_something();
   a=do_something_else();
}
  • No dynamic arrays

Instead of

void
myfunc(int count)
{
   struct mystruct x[count]
}

use

void
myfunc(int count)
{
   struct mystruct *x=g_alloca(count*sizeof(struct mystruct));
}
   
  • Use /* and */ for comments instead of //

Comments

  • Comments for the entire file and classes/structs/methods/functions is the minimum requirement. Examples see below.
  • Please comment your code in a significant and reasonable way.
  • A quick description of (complicated) algorithms makes it easier for other developers and helps them to save a lot of time.
  • Please add a doxygen description for all function you should add. You are wel1come to add it too to older functions. Doxygen result can be found there : http://doxygen.navit-project.org

Example :

/**
* @brief Change the current zoom level, zooming closer to the ground.
*
* This sentence starts the "detailed" description (because this is a new
* paragraph).
*
* @param navit The navit instance
* @param factor The zoom factor, usually 2
* @param p The invariant point (if set to NULL, default to center)
* @returns nothing
*/
void
navit_zoom_in(struct navit *this_, int factor, struct point *p)

Templates

This is an example how you could (should) comment your files and functions. If you have any suggestions for improvement, please feel free to discuss them with us. These templates should be doxygen-conform - if not, please correct them. A more comprehensive overview of possible documentation can be found here.

Files

/** @file can.cpp
 * @brief CAN-Camera Framework :: CAN container class and high level functions
 * 
 * Some documentation regarding this file.
 *
 * @Author Stefan Klumpp <sk@....> 
 * @date 2008
 */
<include "can.h">
.
.
.

Classes/Structs/Functions/Methods

/** 
 * @brief A short description of this function
 *
 * A lot more of documentation regarding this function.
 * @param raw_data Some string to pass to the function
 * @return Nothing
 */

void CanData::processData(string &raw_data)
{
.
.
.
}

Please add yourself to the list of authors, if you make a significant change.