mikroSDK 2.0 coding rules.

Initial version commit.

.gitignore

@@ -0,0 +1,8 @@
+# ignore everything ...
+/*
+# ... but the following
+!/.gitignore
+!/*.md
+!/LICENSE
+!/rules
+!/templates

LICENSE

@@ -0,0 +1,34 @@
+Copyright (C) 2021 MikroElektronika d.o.o.
+Contact: https://www.mikroe.com/contact
+
+This file is part of the mikroSDK package
+
+Commercial License Usage
+
+Licensees holding valid commercial NECTO compilers AI licenses may use this
+file in accordance with the commercial license agreement provided with the
+Software or, alternatively, in accordance with the terms contained in
+a written agreement between you and The MikroElektronika Company.
+For licensing terms and conditions see
+https://www.mikroe.com/legal/software-license-agreement.
+For further information use the contact form at
+https://www.mikroe.com/contact.
+
+
+GNU Lesser General Public License Usage
+
+Alternatively, this file may be used for
+non-commercial projects under the terms of the GNU Lesser
+General Public License version 3 as published by the Free Software
+Foundation: https://www.gnu.org/licenses/lgpl-3.0.html.
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+OF MERCHANTABILITY, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
+OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
+OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,69 @@
+![MikroE](http://www.mikroe.com/img/designs/beta/logo_small.png)
+
+---
+
+# mikroSDK Coding Rules
+
+**Version 1.0.0**
+
+---
+
++ 1 [General Rules](rules/general_rules.md)
+  - 1.1 [Which C](rules/general_rules.md/#11-which-c)
+  - 1.2 [Line Widths](rules/general_rules.md/#12-line-widths)
+  - 1.3 [Braces](rules/general_rules.md/#13-braces)
+  - 1.4 [Parentheses](rules/general_rules.md/#14-parentheses)
+  - 1.5 [Common Abbreviations](rules/general_rules.md/#15-common-abbreviations)
+  - 1.6 [Casts](rules/general_rules.md/#16-casts)
+  - 1.7 [Keywords to Avoid](rules/general_rules.md/#17-keywords-to-avoid)
+  - 1.8 [Keywords to Frequent](rules/general_rules.md/#18-keywords-to-frequent)
++ 2 [Comment Rules](rules/comment_rules.md)
+  - 2.1 [Acceptable Formats](rules/comment_rules.md/#21-acceptable-formats)
+  - 2.2 [Locations and Content](rules/comment_rules.md/#22-locations-and-content)
++ 3 [White Space Rules](rules/white_space_rules.md)
+  - 3.1 [Spaces](rules/white_space_rules.md/#31-spaces)
+  - 3.2 [Alignment](rules/white_space_rules.md/#32-alignment)
+  - 3.3 [Blank Lines](rules/white_space_rules.md/#33-blank-lines)
+  - 3.4 [Indentation](rules/white_space_rules.md/#34-indentation)
+  - 3.5 [Tabs](rules/white_space_rules.md/#35-tabs)
+  - 3.6 [Non-Printing Characters](rules/white_space_rules.md/#36-non-printing-characters)
++ 4 [Module Rules](rules/module_rules.md)
+  - 4.1 [Naming Conventions](rules/module_rules.md/#41-naming-conventions)
+  - 4.2 [Header Files](rules/module_rules.md/#42-header-files)
+  - 4.3 [Source Files](rules/module_rules.md/#43-source-files)
+  - 4.4 [File Templates](rules/module_rules.md/#44-file-templates)
++ 5 [Data Type Rules](rules/data_type_rules.md)
+  - 5.1 [Naming Conventions](rules/data_type_rules.md/#51-naming-conventions)
+  - 5.2 [Fixed-Width Integers](rules/data_type_rules.md/#52-fixed-width-integers)
+  - 5.3 [Signed and Unsigned Integers](rules/data_type_rules.md/#53-signed-and-unsigned-integers)
+  - 5.4 [Floating Point](rules/data_type_rules.md/#54-floating-point)
+  - 5.5 [Structures and Unions](rules/data_type_rules.md/#55-structures-and-unions)
+  - 5.6 [Booleans](rules/data_type_rules.md/#56-booleans)
++ 6 [Procedure Rules](rules/procedure_rules.md)
+  - 6.1 [Naming Conventions](rules/procedure_rules.md/#61-naming-conventions)
+  - 6.2 [Functions](rules/procedure_rules.md/#62-functions)
+  - 6.3 [Function-Like Macros](rules/procedure_rules.md/#63-function-like-macros)
+  - 6.4 [Threads of Execution](rules/procedure_rules.md/#64-threads-of-execution)
+  - 6.5 [Interrupt Service Routines](rules/procedure_rules.md/#65-interrupt-service-routines)
++ 7 [Variable Rules](rules/variable_rules.md)
+  - 7.1 [Naming Conventions](rules/variable_rules.md/#71-naming-conventions)
+  - 7.2 [Initialization](rules/variable_rules.md/#72-initialization)
++ 8 [Statement Rules](rules/statement_rules.md)
+  - 8.1 [Variable Declarations](rules/statement_rules.md/#81-variable-declarations)
+  - 8.2 [Conditional Statements](rules/statement_rules.md/#82-conditional-statements)
+  - 8.3 [Switch Statements](rules/statement_rules.md/#83-switch-statements)
+  - 8.4 [Loops](rules/statement_rules.md/#84-loops)
+  - 8.5 [Jumps](rules/statement_rules.md/#85-jumps)
+  - 8.6 [Equivalence Tests](rules/statement_rules.md/#86-equivalence-tests)
++ 9 [Common abbreviations](rules/abbreviation_table.md)
++ 10 [Templates](templates/template_list.md)
+  - 10.1 [Source template](templates/source_file_template.md)
+  - 10.2 [Header template](templates/header_file_template.md)
+
+---
+
+Version : **1.0.0**
+
+- 1.0.0 / Document initial version created by Strahinja Jacimovic
+
+---

rules/abbreviation_table.md

@@ -0,0 +1,51 @@
+![MikroE](http://www.mikroe.com/img/designs/beta/logo_small.png)
+
+[GO BACK TO MAIN PAGE](../README.md)
+
+---
+## Abbreviation Table
+
+---
+
+| Abbreviation                  |  Meaning                      |
+|:-----------------------------:|:-----------------------------:|
+| ```avg```                     | average                       |
+| ```buf```                     | buffer                        |
+| ```cal```                     | calibration                   |
+| ```cfg```                     | configuration                 |
+| ```curr```                    | current (item in a list)      |
+| ```err```                     | error                         |
+| ```init```                    | initialize                    |
+| ```io```                      | input/output                  |
+| ```isr```                     | interrupt service routine     |
+| ```len```                     | length (of)                   |
+| ```max```                     | maximum                       |
+| ```mgr```                     | manager                       |
+| ```min```                     | minimum                       |
+| ```msec```                    | millisecond                   |
+| ```msg```                     | message                       |
+| ```next```                    | next (item in a list)         |
+| ```nsec```                    | nanosecond                    |
+| ```num```                     | number (of)                   |
+| ```prev```                    | previous (item in a list)     |
+| ```prio```                    | priority                      |
+| ```q```                       | queue                         |
+| ```reg```                     | register                      |
+| ```sem```                     | semaphore                     |
+| ```str```                     | string (null terminated)      |
+| ```sync```                    | synchronize                   |
+| ```temp```                    | temperature                   |
+| ```tmp```                     | temporary                     |
+| ```usec```                    | microsecond                   |
+
+---
+
+[GO BACK TO MAIN PAGE](../README.md)
+
+---
+
+Version : **1.0.0**
+
+- 1.0.0 / Document initial version created by Strahinja Jacimovic
+
+---

rules/comment_rules.md

@@ -0,0 +1,88 @@
+![MikroE](http://www.mikroe.com/img/designs/beta/logo_small.png)
+
+[GO BACK TO MAIN PAGE](../README.md)
+
+---
+## 2 Comment Rules
+
+---
+### 2.1 Acceptable Formats
+
+**Rules:**
+- a. Single-line comments in the **C++** style (i.e., preceded by ```//``` ) should be used for single line comments instead of **C** style (i.e., ```/* ... */``` ).
+- b. **C** style  (i.e., ```/* ... */``` ) comments should be used only for block comments.
+- c. Comments shall never contain the preprocessor tokens ```/*```, ```//```, or ```\```.
+- d. Code shall never be commented out, even temporarily.
+  + I. To temporarily disable a block of code, use the preprocessor’s conditional compilation feature (e.g., ```#if 0``` ... ```#endif``` ).
+  + II. Any line or block of code that exists specifically to increase the level of debug output information shall be surrounded by ```#ifndef NDEBUG``` ... ```#endif``` .
+
+*Example:*
+
+```.c
+/* The following code was meant to be part of the build...
+...
+
+safety_checker();
+
+...
+/* ... but an end of comment character sequence was omitted. */
+```
+
+**Reasoning:**<br /> Whether intentional or not, nested comments run the risk of confusing source code reviewers about the chunks of the code that will be compiled and run. Our choice of negative-logic ```NDEBUG``` is deliberate, as that constant is also associated with disabling the ```assert()``` macro. In both cases, the programmer acts to disable the verbose code.
+
+**Enforcement:**<br /> The use of only permitted comment formats can be partially enforced by the compiler or static analysis. However, only human code reviewers can tell the difference between commented-out code and comments containing descriptive code snippets.
+
+---
+### 2.2 Locations and Content
+
+**Rules:**
+- a. All comments shall be written in clear and complete sentences, with proper spelling and grammar and appropriate punctuation.
+- b. The most useful comments generally precede a block of code that performs one step of a larger algorithm. A blank line shall follow each such code block. The comments in front of the block should be at the same indentation level.
+- c. Avoid explaining the obvious. Assume the reader knows the C programming language. For example, end-of-line comments should only be used where the meaning of that one line of code may be unclear from the variable and function names and operations alone but where a short comment makes it clear. Specifically, avoid writing unhelpful and redundant comments, (e.g., ```numero <<= 2; // Shift numero left 2 bits. ```).
+- d. The number and length of individual comment blocks shall be proportional to the complexity of the code they describe.
+- e. Whenever an algorithm or technical detail is defined in an external reference—e.g., a design specification, patent, or textbook—a comment shall include a sufficient reference to the original source to allow a reader of the code to locate the document.
+- f. Whenever a flow chart or other diagram is needed to sufficiently document the code, the drawing shall be maintained with the source code under version control and the comments should reference the diagram by file name or title.
+- g. All assumptions shall be spelled out in comments.
+- h. Each module and function shall be commented in a manner suitable for automatic documentation generation, e.g., via Doxygen.
+  + i. All documentation which should be used as Doxygen input should be placed inside header (.h) file.
+  + ii. Each public functions must be documented, at least with short description and documentation of function parameters and return value.
+- i. Use the following capitalized comment markers to highlight important issues:
+  + i. ```WARNING:``` alerts a maintainer there is risk in changing this code. For example, that a delay loop counter’s terminal value was determined empirically and may need to change when the code is ported or the optimization level tweaked.
+  + ii. ```NOTE:``` provides descriptive comments about the “why” of a chunk of code—as distinguished from the “how” usually placed in comments. For example, that a chunk of driver code deviates from the datasheet because there was an errata in the chip. Or that an assumption is being made by the original programmer.
+  + iii. ```TODO:``` indicates an area of the code is still under construction and explains what remains to be done. When appropriate, an all-caps programmer name or set of initials may be included before the word TODO (e.g., “ MJB TODO: ”).
+- j. Each comment except single line comment should be preceded and followed by empty line.
+- k. Each start of the block comment ( ```/*``` ) shall appear by itself on the separated line. The corresponding end of block comment ( ```*/``` ) shall appear by itself in the same position the appropriate number of lines later in the file.
+
+*Example:*
+
+```.c
+
+//  Step 1: Batten down the hatches.
+
+for ( int hatch = 0; hatch < NUM_HATCHES; hatch++ ) {
+    if ( hatch_is_open( hatches[hatch] ) ) {
+        hatch_close( hatches[hatch] );
+    }
+}
+
+/*
+    Step 2: Raise the mizzenmast.
+    TODO: Define mizzenmast driver API.
+*/
+```
+
+**Reasoning:**<br /> Following these rules results in good comments. And good comments correlate with good code. It is a best practice to write the comments before writing the code that implements the behaviors those comments outline. Unfortunately, it is easy for source code and documentation to drift over time. The best way to prevent this is to keep the documentation as close to the code as possible. Likewise, anytime a question is asked about a section of the code that was previously thought to be clear, you should add a comment addressing that issue nearby. Doxygen is a useful tool to generate documentation describing the modules, functions, and parameters of an API for its users. However, comments are also still necessary inside the function bodies to reduce the cost of code maintenance.
+
+**Enforcement:**<br /> The quality of comments shall be evaluated during code reviews. Code reviewers should verify that comments accurately describe the code and are also clear, concise, and valuable. Automatically generated documentation should be rebuilt each time the software is built.
+
+---
+
+[GO BACK TO MAIN PAGE](../README.md)
+
+---
+
+Version : **1.0.0**
+
+- 1.0.0 / Document initial version created by Strahinja Jacimovic
+
+---