Difference between revisions of "Programming guidelines"

From Navit's Wiki
Jump to: navigation, search
(Comments)
(Comments: add detailed description)
Line 7: Line 7:
 
Example :
 
Example :
 
  /**
 
  /**
  * Change the current zoom level, zooming closer to the ground
+
  * @brief Change the current zoom level, zooming closer to the ground.
 +
* This sentence starts the "detailed" description.
 
  *
 
  *
 
  * @param navit The navit instance
 
  * @param navit The navit instance

Revision as of 15:21, 1 May 2011

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 welcome 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.
*
* @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.