Merge branch 'doc/style_guide_headers' into 'master'

docs: style guide: add note about header guards and include file order

See merge request espressif/esp-idf!13129

docs/en/contribute/style-guide.rst

@@ -16,6 +16,8 @@ When doing modifications to third-party code used in ESP-IDF, follow the way tha
 C Code Formatting
 -----------------
 
+.. highlight:: c
+
 .. _style-guide-naming:
 
 Naming
@@ -178,7 +180,9 @@ Commits should only contain files with LF (Unix style) endings.
 
 Windows users can configure git to check out CRLF (Windows style) endings locally and commit LF endings by setting the ``core.autocrlf`` setting. `Github has a document about setting this option <github-line-endings>`. However because MSYS2 uses Unix-style line endings, it is often easier to configure your text editor to use LF (Unix style) endings when editing ESP-IDF source files.
 
-If you accidentally have some commits in your branch that add LF endings, you can convert them to Unix by running this command in an MSYS2 or Unix terminal (change directory to the IDF working directory and check the correct branch is currently checked out, beforehand)::
+If you accidentally have some commits in your branch that add LF endings, you can convert them to Unix by running this command in an MSYS2 or Unix terminal (change directory to the IDF working directory and check the correct branch is currently checked out, beforehand):
+
+.. code-block:: bash
 
   git rebase --exec 'git diff-tree --no-commit-id --name-only -r HEAD | xargs dos2unix && git commit -a --amend --no-edit --allow-empty' master
 
@@ -193,7 +197,9 @@ You can use ``astyle`` program to format your code according to the above recomm
 
 If you are writing a file from scratch, or doing a complete rewrite, feel free to re-format the entire file. If you are changing a small portion of file, don't re-format the code you didn't change. This will help others when they review your changes.
 
-To re-format a file, run::
+To re-format a file, run:
+
+.. code-block:: bash
 
     tools/format.sh components/my_component/file.c
 
@@ -257,6 +263,54 @@ If the variable is declared separately, for example if it is used for multiple a
   assert(res != 0);
 
 
+Header file guards
+------------------
+
+All public facing header files should have preprocessor guards. A pragma is preferred::
+
+    #pragma once
+
+over the following pattern::
+
+    #ifndef FILE_NAME_H
+    #define FILE_NAME_H
+    ...
+    #endif // FILE_NAME_H
+
+In addition to guard macros, all C header files should have ``extern "C"`` guards to allow the header to be used from C++ code. Note that the following order should be used: ``pragma once``, then any ``#include`` statements, then ``extern "C"`` guards::
+
+    #pragma once
+
+    #include <stdint.h>
+
+    #ifdef __cplusplus
+    extern "C" {
+    #endif
+
+    /* declarations go here */
+
+    #ifdef __cplusplus
+    }
+    #endif
+
+
+Include statements
+------------------
+
+When writing ``#include`` statements, try to maintain the following order:
+
+* C standard library headers.
+* Other POSIX standard headers and common extensions to them (such as ``sys/queue.h``.)
+* Common IDF headers (``esp_log.h``, ``esp_system.h``, ``esp_timer.h``, ``esp_sleep.h``, etc.)
+* Headers of other components, such as FreeRTOS.
+* Public headers of the current component.
+* Private headers.
+
+Use angle brackets for C standard library headers and other POSIX headers (``#include <stdio.h>``).
+
+Use double quotes for all other headers (``#include "esp_log.h"``).
+
+
 C++ Code Formatting
 -------------------
 
@@ -264,7 +318,7 @@ The same rules as for C apply. Where they are not enough, apply the following ru
 
 File Naming
 ^^^^^^^^^^^^
-C++ Header files have the extension ``.hpp``. C++ source files have the extension ``.cpp``. The latter is important for the compiler to distiguish them from normal C source files.
+C++ Header files have the extension ``.hpp``. C++ source files have the extension ``.cpp``. The latter is important for the compiler to distinguish them from normal C source files.
 
 Naming
 ^^^^^^