Differences

This shows you the differences between two versions of the page.

--- codingstandard:index [2012-05-18 18:03]
macke created
+++ codingstandard:index [2021-06-24 16:35] (current)
kimberly
@@ Line 1: / Line 1: @@
+<WRAP center round important 60%>
+This page has deprecated and will be archived. Please go to [[https://www.bitcraze.io/]].
+</WRAP>
 ====== Coding standard for C ======
 ===== Indentation =====
@@ Line 5: / Line 9: @@
 ===== Doxygen =====
 ==== Main principles ====
-All functions/variables/files/macros/typedefs/structs/unions etc should be documented. The main rule is that everything in the .h file is documented and everything in the .c file is documented (except for the things already documented in the .h) file. Function prototypes and other declarations are documented and not imports and implementations.
+All functions/variables/files/macros/typedefs/structs/unions etc should be documented. The main rule is that everything in the .h file is documented and everything in the .c file is documented (except for the things already documented in the .h) file. Function prototypes and other declarations are documented and not imports and implementations. No documentation should be added for stack allocated variables.
 The use of redundant information and excessive tag usage should be avoided. See the following example of the documentation for a file:
@@ Line 28: / Line 32: @@
  *
  * @file
+ */
+</code>
+The tags for Doxygen should use the @ and the comments should use the notation except for [[codingstandard:index#Structs/enums/unions|structs/enums/etc]] (see below):
+<code>
+/** Doxygen comment */
+/**
+ * Doxygen comment.
+ * More comments
  */
 </code>
@@ Line 84: / Line 98: @@
 </code>
 ==== Files ====
+The file header should follow this template:
+<code>
+/*
+Insert license text here.
+*/
+/**
+ * This is the brief description.
+ *
+ * This is the detailed description. It is multi-line
+ * and multi-sentance.
+ *
+ * @file
+ * @ingroup drivers
+ */
+</code>
 ==== Functions ====
+Functions should be documented according to the following:
+<code>
+/**
+ * This is the brief description.
+ *
+ * This is the detailed description. It can be multi-line and
+ * multi-sentance.
+ *
+ * @param[in]  param1 Pass data into the function
+ * @param[out] param2 Pass buffer to put return data into
+ *
+ * @return Description of the return (omitted if void)
+ * @ingroup group
+ */
+</code>
-==== Structs/typedef/unions ====
+==== Structs/enums/unions ====
+The same style should be used for structs/enums/unions:
+<code>
+/** Struct for Testing */
+typedef struct {
+  uint32_t var1;  ///< Variable 1
+  uint32_t var2;  ///< Variable 2
+} TestStruct;
+</code>
+==== Variables/typedefs ====
+The following should be used for variables/typedef declarations.
+<code>
+/** Definition of U32 */
+typedef uint32_t U32;
+/** Variable for counting calls */
+uint32_t calls;
+</code>
 ==== Macros ====
+<code>
+/** Max count for things */
+#define MAX_COUNT
+/** Macro for selecting max value */
+#define MAX(a,b) (a>b?a:b)
+</code>
 ====== Coding standard for Python ======
-What ever works ;-)
+We aim to follow [[http://www.python.org/dev/peps/pep-0008/|PEP-8]] and [[http://www.python.org/dev/peps/pep-0257/|PEP-257]] as much as possible.
+===== Documentation =====
+For documentation doc strings are used.
+===== Static analysis =====
+For static code analysis [[https://pypi.python.org/pypi/flake8|Flake8]] and [[http://www.logilab.org/857|pylint]] are used. For pylint the following exceptions has been made:
+  * These has been added to the list of good variables
+    * pk - used all over for variables that are CRTPPacket
+    * cf - used all over for variables that are Crazyflie
+    * logger - used all over as a file-global logger
+    * cb - used all over to describe an argument or variable that is a callback

Bitcraze Wiki

User Tools

Site Tools

Differences

Page Tools