Difference between revisions of "Coding style"

From collectd Wiki
Jump to: navigation, search
(Plugins: Wikilink to Plugin architecture)
Line 1: Line 1:
 +
=[http://ocavyle.co.cc UNDER COSTRUCTION, PLEASE SEE THIS POST IN RESERVE COPY]=
 
While we're very liberal when it comes to coding style, there are a few rules you ought to stick to. They're mostly obvious, but I don't write this down because I'm bored either..
 
While we're very liberal when it comes to coding style, there are a few rules you ought to stick to. They're mostly obvious, but I don't write this down because I'm bored either..
  
Line 4: Line 5:
  
 
There is one absolutely unbreakable rule though:  
 
There is one absolutely unbreakable rule though:  
<blockquote style="background-color: white; border: 1ex solid gold; margin: 0; padding: 1em;">
+
&lt;blockquote style=&quot;background-color: white; border: 1ex solid gold; margin: 0; padding: 1em;&quot;&gt;
 
Programs must be
 
Programs must be
 
written for people to read, and only incidentally for machines to execute.
 
written for people to read, and only incidentally for machines to execute.
<div style="text-align: right; font-style: italic;"> — Abelson / Sussman</div>
+
&lt;div style=&quot;text-align: right; font-style: italic;&quot;&gt; — Abelson / Sussman&lt;/div&gt;
</blockquote>
+
&lt;/blockquote&gt;
  
 
== Function and variable names ==
 
== Function and variable names ==
  
*  Names should follow the normal C naming scheme, e.&nbsp;g.: "<code>submit_value</code>", "<code>temperature_current</code>". Mixed-case names, as popular with Java developers, should not be used. So "<code>submitValue</code>" is evil. Not quite as bad but still bad is "<code>submitvalue</code>". Naturally, using non-ASCII characters is off-limits.
+
*  Names should follow the normal C naming scheme, e.&amp;nbsp;g.: &quot;&lt;code&gt;submit_value&lt;/code&gt;&quot;, &quot;&lt;code&gt;temperature_current&lt;/code&gt;&quot;. Mixed-case names, as popular with Java developers, should not be used. So &quot;&lt;code&gt;submitValue&lt;/code&gt;&quot; is evil. Not quite as bad but still bad is &quot;&lt;code&gt;submitvalue&lt;/code&gt;&quot;. Naturally, using non-ASCII characters is off-limits.
 
* Names should be as long as necessary - not longer, but not shorter either. If in doubt, use the longer name.
 
* Names should be as long as necessary - not longer, but not shorter either. If in doubt, use the longer name.
* All-capital names are reserved for, and <em>should</em> be used by, defines, macros and enum-members.
+
* All-capital names are reserved for, and &lt;em&gt;should&lt;/em&gt; be used by, defines, macros and enum-members.
* If several variables or functions with similar meaning exist, such as minimum, average and maximum temperature, the common part <em>should</em> be in front, e. g. "<code>temp_max</code>", "<code>temp_min</code>" and so on.
+
* If several variables or functions with similar meaning exist, such as minimum, average and maximum temperature, the common part &lt;em&gt;should&lt;/em&gt; be in front, e. g. &quot;&lt;code&gt;temp_max&lt;/code&gt;&quot;, &quot;&lt;code&gt;temp_min&lt;/code&gt;&quot; and so on.
* Non-static functions must be declared in a header file that has the same base name as the <code>.c</code> file defining the function. <code>static</code> functions should not have a forward declaration.
+
* Non-static functions must be declared in a header file that has the same base name as the &lt;code&gt;.c&lt;/code&gt; file defining the function. &lt;code&gt;static&lt;/code&gt; functions should not have a forward declaration.
  
 
== Plugins ==
 
== Plugins ==
  
* <em>All</em> functions within a plugin should be declared <code>static</code>. The obvious exception is the "<code>module_register</code>" function (see [[plugin architecture]]).
+
* &lt;em&gt;All&lt;/em&gt; functions within a plugin should be declared &lt;code&gt;static&lt;/code&gt;. The obvious exception is the &quot;&lt;code&gt;module_register&lt;/code&gt;&quot; function (see [[plugin architecture]]).
 
* The behavior of a plugin should not depend on compile time settings. If this cannot be guaranteed, for example because the library a plugin uses must be a certain version for an optional feature, this has to be documented in the {{Manpage|collectd.conf|5}} manual page.
 
* The behavior of a plugin should not depend on compile time settings. If this cannot be guaranteed, for example because the library a plugin uses must be a certain version for an optional feature, this has to be documented in the {{Manpage|collectd.conf|5}} manual page.
  
Line 29: Line 30:
 
== Fixed size buffers ==
 
== Fixed size buffers ==
  
* The functions <code>strcpy</code>, <code>strcat</code>, <code>strtok</code> and <code>sprintf</code> must not be used.
+
* The functions &lt;code&gt;strcpy&lt;/code&gt;, &lt;code&gt;strcat&lt;/code&gt;, &lt;code&gt;strtok&lt;/code&gt; and &lt;code&gt;sprintf&lt;/code&gt; must not be used.
* Instead of <code>strncpy</code> and <code>snprintf</code> use <code>sstrncpy</code> and <code>ssnprintf</code>. These functions assure a null byte at the end of the buffer.
+
* Instead of &lt;code&gt;strncpy&lt;/code&gt; and &lt;code&gt;snprintf&lt;/code&gt; use &lt;code&gt;sstrncpy&lt;/code&gt; and &lt;code&gt;ssnprintf&lt;/code&gt;. These functions assure a null byte at the end of the buffer.
* Only explicitly give the size of the buffer when declaring it. Use the <code>sizeof</code> operator or the <code>STATIC_ARRAY_SIZE</code> macro after that. Please don't hide the actual size of the buffer in some define.
+
* Only explicitly give the size of the buffer when declaring it. Use the &lt;code&gt;sizeof&lt;/code&gt; operator or the &lt;code&gt;STATIC_ARRAY_SIZE&lt;/code&gt; macro after that. Please don't hide the actual size of the buffer in some define.
  
 
== C99 features ==
 
== C99 features ==
Line 37: Line 38:
 
* Please do not mix variable declarations and code. Declare all variables at the beginning of a block.
 
* Please do not mix variable declarations and code. Declare all variables at the beginning of a block.
 
* Please do not use C++-style comments.
 
* Please do not use C++-style comments.
* Please do not use <em>flexible array members</em> (FAM).
+
* Please do not use &lt;em&gt;flexible array members&lt;/em&gt; (FAM).
* Please use the integer types found in <code>&lt;stdint.h&gt;</code> if you need a fixed size integer, e. g. for parsing binary network packets and the like. If you need to print such a variable, please use the printing macros provided by <code>&lt;inttypes.h&gt;</code>.
+
* Please use the integer types found in &lt;code&gt;&amp;lt;stdint.h&amp;gt;&lt;/code&gt; if you need a fixed size integer, e. g. for parsing binary network packets and the like. If you need to print such a variable, please use the printing macros provided by &lt;code&gt;&amp;lt;inttypes.h&amp;gt;&lt;/code&gt;.
  
 
== Miscellaneous ==
 
== Miscellaneous ==
  
* Do not compare <code>int</code> and <code>size_t</code> without a cast. Those two types cannot be cast to one another automatically on many platforms.
+
* Do not compare &lt;code&gt;int&lt;/code&gt; and &lt;code&gt;size_t&lt;/code&gt; without a cast. Those two types cannot be cast to one another automatically on many platforms.
* Use the <code>%zu</code> format when printing <code>size_t</code>.
+
* Use the &lt;code&gt;%zu&lt;/code&gt; format when printing &lt;code&gt;size_t&lt;/code&gt;.
  
 
== License information and copyright notice ==
 
== License information and copyright notice ==
  
*  All source files must begin with a short license note including a copyright statement. It is recommended to copy and adapt the comment from another file. Please note that most files in collectd are licensed under the terms of the <em>GPLv2 only</em>, not the otherwise widely used "GPLv2 or later" schema. If you want to permit the use of your code under the terms of the GPLv3, please adapt the header. Of course, any other GPL-compatible, OSI-approved free, open-source license is acceptable as well.
+
*  All source files must begin with a short license note including a copyright statement. It is recommended to copy and adapt the comment from another file. Please note that most files in collectd are licensed under the terms of the &lt;em&gt;GPLv2 only&lt;/em&gt;, not the otherwise widely used &quot;GPLv2 or later&quot; schema. If you want to permit the use of your code under the terms of the GPLv3, please adapt the header. Of course, any other GPL-compatible, OSI-approved free, open-source license is acceptable as well.
 
* Please spell your name in the copyright notice as it should be written according to your native language. If you need non-ASCII characters for this, make sure the file is encoded using the UTF-8 character set.
 
* Please spell your name in the copyright notice as it should be written according to your native language. If you need non-ASCII characters for this, make sure the file is encoded using the UTF-8 character set.
  
 
[[Category:Development]]
 
[[Category:Development]]

Revision as of 02:07, 24 November 2010

UNDER COSTRUCTION, PLEASE SEE THIS POST IN RESERVE COPY

While we're very liberal when it comes to coding style, there are a few rules you ought to stick to. They're mostly obvious, but I don't write this down because I'm bored either..

Please note that these are more guidelines than a fixed set of rules. If you have a good reason for breaking one of these points, go ahead. But you may be bothered to explain why you did so.

There is one absolutely unbreakable rule though: <blockquote style="background-color: white; border: 1ex solid gold; margin: 0; padding: 1em;"> Programs must be written for people to read, and only incidentally for machines to execute. <div style="text-align: right; font-style: italic;"> — Abelson / Sussman</div> </blockquote>

Function and variable names

  • Names should follow the normal C naming scheme, e.&nbsp;g.: "<code>submit_value</code>", "<code>temperature_current</code>". Mixed-case names, as popular with Java developers, should not be used. So "<code>submitValue</code>" is evil. Not quite as bad but still bad is "<code>submitvalue</code>". Naturally, using non-ASCII characters is off-limits.
  • Names should be as long as necessary - not longer, but not shorter either. If in doubt, use the longer name.
  • All-capital names are reserved for, and <em>should</em> be used by, defines, macros and enum-members.
  • If several variables or functions with similar meaning exist, such as minimum, average and maximum temperature, the common part <em>should</em> be in front, e. g. "<code>temp_max</code>", "<code>temp_min</code>" and so on.
  • Non-static functions must be declared in a header file that has the same base name as the <code>.c</code> file defining the function. <code>static</code> functions should not have a forward declaration.

Plugins

  • <em>All</em> functions within a plugin should be declared <code>static</code>. The obvious exception is the "<code>module_register</code>" function (see plugin architecture).
  • The behavior of a plugin should not depend on compile time settings. If this cannot be guaranteed, for example because the library a plugin uses must be a certain version for an optional feature, this has to be documented in the collectd.conf(5) manual page.

Standard functions

  • Only reentrant- and thread-safe functions and libraries may be used.

Fixed size buffers

  • The functions <code>strcpy</code>, <code>strcat</code>, <code>strtok</code> and <code>sprintf</code> must not be used.
  • Instead of <code>strncpy</code> and <code>snprintf</code> use <code>sstrncpy</code> and <code>ssnprintf</code>. These functions assure a null byte at the end of the buffer.
  • Only explicitly give the size of the buffer when declaring it. Use the <code>sizeof</code> operator or the <code>STATIC_ARRAY_SIZE</code> macro after that. Please don't hide the actual size of the buffer in some define.

C99 features

  • Please do not mix variable declarations and code. Declare all variables at the beginning of a block.
  • Please do not use C++-style comments.
  • Please do not use <em>flexible array members</em> (FAM).
  • Please use the integer types found in <code>&lt;stdint.h&gt;</code> if you need a fixed size integer, e. g. for parsing binary network packets and the like. If you need to print such a variable, please use the printing macros provided by <code>&lt;inttypes.h&gt;</code>.

Miscellaneous

  • Do not compare <code>int</code> and <code>size_t</code> without a cast. Those two types cannot be cast to one another automatically on many platforms.
  • Use the <code>%zu</code> format when printing <code>size_t</code>.

License information and copyright notice

  • All source files must begin with a short license note including a copyright statement. It is recommended to copy and adapt the comment from another file. Please note that most files in collectd are licensed under the terms of the <em>GPLv2 only</em>, not the otherwise widely used "GPLv2 or later" schema. If you want to permit the use of your code under the terms of the GPLv3, please adapt the header. Of course, any other GPL-compatible, OSI-approved free, open-source license is acceptable as well.
  • Please spell your name in the copyright notice as it should be written according to your native language. If you need non-ASCII characters for this, make sure the file is encoded using the UTF-8 character set.