Difference between revisions of "Coding style"

From collectd Wiki
Jump to: navigation, search
(CLICK HERE TO ENTER DRUGSTORE)
(C standard: Add a note that C11 would be acceptable, too.)
 
(14 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<br /><br /><center><h1> <http>//trusted-pharmacy.org/ CLICK HERE TO ENTER DRUGSTORE! ] </h1><br /></center>
+
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..
<br />
+
 
<br /><br />
+
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.
<br /><br />
+
 
<br /><br />
+
There is one absolutely unbreakable rule though:
<br /><br />
+
<blockquote style="background-color: white; border: 1ex solid gold; margin: 0; padding: 1em;">
<br /><br />
+
Programs must be
<br /><br />
+
written for people to read, and only incidentally for machines to execute.
<br /><br />
+
<div style="text-align: right; font-style: italic;"> — Abelson / Sussman</div>
<br /><br />
+
</blockquote>
<br /><br />
+
 
<br /><br />
+
== Formatting ==
<br /><br />
+
 
<br /><br />
+
All code ''must'' be formatted with [https://clang.llvm.org/docs/ClangFormat.html clang-format]. Since the exact formatting sometimes differs between versions of clang-format, we recommend you use the <code>contrib/format.sh</code> shell script which uses the same service for formatting as the check on Github.
 
+
 
 
+
== Function and variable names ==
Atarax discount
+
 
  <br />
+
* Names should follow the '''snake_case''' (lowercase with underscores) naming scheme, e.g.: "<code>submit_value</code>", "<code>temperature_current</code>". Mixed-case names, as popular with Java developers, should not be used, i.e. don't use "<code>submitValue</code>".
acheter Flomax oline
+
* Do not use non-ASCII characters in variable and function names.
  <br /
+
* Names should be as long as necessary – not longer, but not shorter either. If in doubt, use the more descriptive (longer) name.
order Strattera
+
* All-capital names are reserved for, and ''should'' be used by, defines, macros and enum-members.
   <br />
+
* If several variables or functions with similar meaning exist, such as minimum, average and maximum temperature, the common part ''should'' be in front, e.g. "<code>temp_max</code>", "<code>temp_min</code>" and so on.
buy Cyklokapron
+
* 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 style="color: darkgreen;">static</code> functions should not have a forward declaration.
  <br /
+
 
online pharmacy Caduet
+
== Plugins ==
   <br /
+
 
buy Famvir online
+
* <em>All</em> functions within a plugin should be declared <code style="color: darkgreen;">static</code>. The obvious exception is the "<code>module_register</code>" function (see [[plugin architecture]]).
  <br />
+
* 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.
Wellbutrin Sr price
+
 
  <br />
+
== Standard functions ==
acheter Lotensin oline
+
 
  <br />
+
* Only reentrant- and thread-safe functions and libraries may be used.
comprar Micronase
+
 
  <br />
+
== Strings ==
comprar Micardis Hct
+
 
  <br />
+
* Many convenience functions are available from '''<code>"common.h"</code>'''.
order Neurontin online
+
* The functions <code>strcpy</code>, <code>strcat</code>, <code>strtok</code> and <code>sprintf</code> don't take a buffer size and must not be used. If possible, use an alternative from <code>"common.h"</code>.
  <br />
+
* Instead of <code>strncpy</code> use <code>sstrncpy</code> . This function assures a null byte at the end of the buffer.
order Ziac
+
* Only explicitly give the size of the buffer when declaring it. Later, use <code>sizeof</code> to get its size in bytes and the <code>STATIC_ARRAY_SIZE</code> macro to get the number of elements. For example:<source lang="c">
  <br />
+
example_t *ex = calloc(1, sizeof(*ex));
order Diprolene online
+
sstrncpy(buffer, "example", sizeof(buffer));
  <br />
+
size_t keys_num = STATIC_ARRAY_SIZE(keys);
Effexor price
+
</source>
  <br />
+
 
Plan B price
+
== C standard ==
  <br />
+
 
order Crixivan
+
Most of ''collectd'' is using the C99 standard, but if you'd like to use C11 features for a plugin we're not going to stop you. Regularly used C99 features include:
  <br />
+
 
no perscription Imdur
+
* Mixed declarations, i.e. defining variables as late as possible. See also: https://collectd.org/review-comments#define-variables-on-first-use
  <br />
+
* Designated struct initializers, for example:<source lang="c">
online pharmacy Tofranil
+
/* initialize using designated initializers */
  <br />
+
struct timespec ts = {
acheter Asacol
+
  .tv_sec = 2,
  <br />
+
   .tv_nsec = 500000000,
Feldene price
+
}
  <br />
+
</source>
Microzide tablets
+
* Compound literals, for example:<source lang="c">
  <br />
+
/* Initialize allocated memory: */
Droxia price
+
*ptr = (struct example){
  <br />
+
   .answer = 42,
buy Microzide
+
};
  <br />
+
 
order Lotensin online
+
/* Compound literals can also be used to "cast" a gauge_t (and friends) to a value_t: */
  <br />
+
submit("example", (value_t){.gauge = g});
cheap Vepesid
+
</source>
  <br />
+
* Variable Length Arrays, for example:<source lang="c">
Vaseretic discount
+
char copy[strlen(orig) + 1] = {0};
  <br /> 
+
</source>
buy Aventyl online
+
* Please do not mix the <code style="color: navy;">// …</code> and <code style="color: navy;">/* … */</code> comment styles. Using <code style="color: navy;">/* … */</code> for the license header and <code style="color: navy;">// …</code> for everything else is okay.
  <br />  
+
* Please do not use ''flexible array members'' (FAM).
kaufen Combivir
+
* Please use the integer types found in <code style="color: maroon;">&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 style="color: maroon;">&lt;inttypes.h&gt;</code>.
  <br /
+
* Feel free to use the <code style="color: darkgreen;">bool</code> type. Assign only the values <code>true</code> and <code>false</code> to these variables.
buy cheap Eulexin
+
 
  <br />
+
== Miscellaneous ==
comprar Ceclor
+
 
  <br />
+
* Do not compare <code style="color: darkgreen;">int</code> and <code style="color: darkgreen;">size_t</code> without a cast. Those two types cannot be cast to one another automatically on many platforms.
order Starlix online
+
* Use the <code style="color: magenta;">%zu</code> format when printing <code style="color: darkgreen;">size_t</code>.
  <br />
+
 
 +
== License information and copyright notice ==
 +
 
 +
* All source files must begin with a short license note including a copyright statement. We recommended to copy and adapt the comment from another file.
 +
* Any GPLv2 compatible, OSI approved, free&nbsp;/ open-source license is acceptable.
 +
* For new files, we ''recommend'' to use the [[:Category:MIT License|MIT license]].
 +
* ''GPL:'' 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.
 +
* 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]]

Latest revision as of 09:19, 30 October 2018

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:

Programs must be written for people to read, and only incidentally for machines to execute.

— Abelson / Sussman

Formatting

All code must be formatted with clang-format. Since the exact formatting sometimes differs between versions of clang-format, we recommend you use the contrib/format.sh shell script which uses the same service for formatting as the check on Github.

Function and variable names

  • Names should follow the snake_case (lowercase with underscores) naming scheme, e.g.: "submit_value", "temperature_current". Mixed-case names, as popular with Java developers, should not be used, i.e. don't use "submitValue".
  • Do not use non-ASCII characters in variable and function names.
  • Names should be as long as necessary – not longer, but not shorter either. If in doubt, use the more descriptive (longer) name.
  • All-capital names are reserved for, and should 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 should be in front, e.g. "temp_max", "temp_min" and so on.
  • Non-static functions must be declared in a header file that has the same base name as the .c file defining the function. static functions should not have a forward declaration.

Plugins

  • All functions within a plugin should be declared static. The obvious exception is the "module_register" 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.

Strings

  • Many convenience functions are available from "common.h".
  • The functions strcpy, strcat, strtok and sprintf don't take a buffer size and must not be used. If possible, use an alternative from "common.h".
  • Instead of strncpy use sstrncpy . This function assures a null byte at the end of the buffer.
  • Only explicitly give the size of the buffer when declaring it. Later, use sizeof to get its size in bytes and the STATIC_ARRAY_SIZE macro to get the number of elements. For example:
    example_t *ex = calloc(1, sizeof(*ex));
    sstrncpy(buffer, "example", sizeof(buffer));
    size_t keys_num = STATIC_ARRAY_SIZE(keys);
    

C standard

Most of collectd is using the C99 standard, but if you'd like to use C11 features for a plugin we're not going to stop you. Regularly used C99 features include:

  • Mixed declarations, i.e. defining variables as late as possible. See also: https://collectd.org/review-comments#define-variables-on-first-use
  • Designated struct initializers, for example:
    /* initialize using designated initializers */
    struct timespec ts = {
      .tv_sec = 2,
      .tv_nsec = 500000000,
    }
    
  • Compound literals, for example:
    /* Initialize allocated memory: */
    *ptr = (struct example){
      .answer = 42,
    };
    
    /* Compound literals can also be used to "cast" a gauge_t (and friends) to a value_t: */
    submit("example", (value_t){.gauge = g});
    
  • Variable Length Arrays, for example:
    char copy[strlen(orig) + 1] = {0};
    
  • Please do not mix the // … and /* … */ comment styles. Using /* … */ for the license header and // … for everything else is okay.
  • Please do not use flexible array members (FAM).
  • Please use the integer types found in <stdint.h> 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 <inttypes.h>.
  • Feel free to use the bool type. Assign only the values true and false to these variables.

Miscellaneous

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

License information and copyright notice

  • All source files must begin with a short license note including a copyright statement. We recommended to copy and adapt the comment from another file.
  • Any GPLv2 compatible, OSI approved, free / open-source license is acceptable.
  • For new files, we recommend to use the MIT license.
  • GPL: Please note that most files in collectd are licensed under the terms of the GPLv2 only, 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.
  • 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.