Difference between revisions of "Programming guidelines"

From Navit's Wiki
Jump to: navigation, search
(intro, cat)
(c highlightning)
Line 8: Line 8:
  
 
indent usage:
 
indent usage:
 
+
<source lang="c">
 
     indent --procnames-start-lines --k-and-r-style --indent-level 8
 
     indent --procnames-start-lines --k-and-r-style --indent-level 8
 
+
</source>
 
== Character encoding and line breaks ==
 
== Character encoding and line breaks ==
  
Line 20: Line 20:
 
* No inline declarations of variables
 
* No inline declarations of variables
 
Instead of
 
Instead of
 
+
<source lang="c">
 
  {
 
  {
 
     do_something();
 
     do_something();
 
     int a=do_something_else();
 
     int a=do_something_else();
 
  }
 
  }
 +
</source>
  
 
use
 
use
  
 +
<source lang="c">
 
  {
 
  {
 
     int a;
 
     int a;
Line 33: Line 35:
 
     a=do_something_else();
 
     a=do_something_else();
 
  }
 
  }
 +
</source>
 +
 
* No dynamic arrays
 
* No dynamic arrays
 
Instead of
 
Instead of
  
 +
<source lang="c">
 
  void
 
  void
 
  myfunc(int count)
 
  myfunc(int count)
Line 41: Line 46:
 
     struct mystruct x[count]
 
     struct mystruct x[count]
 
  }
 
  }
 +
</source>
  
 
use
 
use
  
 +
<source lang="c">
 
  void
 
  void
 
  myfunc(int count)
 
  myfunc(int count)
Line 49: Line 56:
 
     struct mystruct *x=g_alloca(count*sizeof(struct mystruct));
 
     struct mystruct *x=g_alloca(count*sizeof(struct mystruct));
 
  }
 
  }
   
+
</source>   
 +
 
 
* Use /* and */ for comments instead of //
 
* Use /* and */ for comments instead of //
  
Line 65: Line 73:
  
 
Example :
 
Example :
 +
 +
<source lang="c">
 
  /**
 
  /**
 
  * @brief Change the current zoom level, zooming closer to the ground.
 
  * @brief Change the current zoom level, zooming closer to the ground.
Line 78: Line 88:
 
  void
 
  void
 
  navit_zoom_in(struct navit *this_, int factor, struct point *p)
 
  navit_zoom_in(struct navit *this_, int factor, struct point *p)
 +
</source>
  
 
=== Templates ===
 
=== Templates ===
Line 83: Line 94:
 
   
 
   
 
==== Files ====
 
==== Files ====
<pre>
+
 
 +
<source lang="c">
 
/** @file can.cpp
 
/** @file can.cpp
 
  * @brief CAN-Camera Framework :: CAN container class and high level functions
 
  * @brief CAN-Camera Framework :: CAN container class and high level functions
Line 96: Line 108:
 
.
 
.
 
.
 
.
</pre>
+
</source>
  
 
==== Classes/Structs/Functions/Methods ====
 
==== Classes/Structs/Functions/Methods ====
<pre>
+
 
 +
<source lang="c">
 
/**  
 
/**  
 
  * @brief A short description of this function
 
  * @brief A short description of this function
Line 114: Line 127:
 
.
 
.
 
}
 
}
</pre>
+
</source>
  
 
Please add yourself to the list of authors, if you make a significant change.
 
Please add yourself to the list of authors, if you make a significant change.
Line 120: Line 133:
  
 
[[Category:Development]]
 
[[Category:Development]]
 +
[[Category:Support]]

Revision as of 18:49, 16 December 2012

NAVIT is a team-project, thus a lot of coders working on it's development and codebase. To get a unified coding style and make it easier for everybody to work with parts, that someone else wrote, we tried to specify the formating of our source as following and how we deal with third party modules.

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

Character encoding and line breaks

All non-ascii-strings must be utf-8 encoded. Line breaks consist of a linefeed (no carriage return)

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 //

Use of libraries

  • Navit uses GLib extensively. In general, code should use GLib's functions in preference to functions from libc. For example, use g_new() / g_free(), rather than malloc() / free(), g_strcmp0() rather than strcmp() etc.
  • Unfortunately, not all platforms that Navit runs on have a native GLib version. For these platforms, there is code replacing these libraries under navit/support/. Take care to only use functions from GLib (or other libraries), that is also present under navit/support/. If you need something that is not present there, please discuss it on IRC - it may be possible to add it to the support code.

Comments

General guidelines

  • 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 we1come 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.