doc: Update U-Boot coding style guide with clang-format usage

The U-Boot coding style guide has been updated to include information
about using the `.clang-format` configuration file for automatic code
formatting. This ensures consistent formatting across the entire
codebase and aligns with Linux kernel coding standards. The goal with
introducing a predefined coding style is consistency rather than
personal preference.

The .clang-format file is copied directly from the Linux kernel without
any modifications, ensuring complete compatibility with kernel coding
standards.

Include comprehensive best practices for using clang-format,
specifically guidance on formatting only changed blocks versus entire
files, creating separate formatting-only commits for better code review,
and leveraging git clang-format for targeted formatting. Add examples of
editor integrations. This enhancement will help maintainers and
contributors to easily adhere to U-Boot coding standards.

Signed-off-by: Javier Tia <[email protected]>

1 files changed, 79 insertions, 2 deletions

diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst
index bc18b2ebb7b..10bfa747c6c 100644
--- a/doc/develop/codingstyle.rst
+++ b/doc/develop/codingstyle.rst
@@ -12,8 +12,9 @@ or only minimal changes.
 The following rules apply:
 
 * All contributions to U-Boot should conform to the `Linux kernel
-  coding style <https://www.kernel.org/doc/html/latest/process/coding-style.html>`_
-  and the `Lindent script <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/scripts/Lindent>`_.
+  coding style <https://www.kernel.org/doc/html/latest/process/coding-style.html>`_.
+  U-Boot includes a `.clang-format` configuration file that can be used to
+  automatically format code according to these standards.
   * The exception for net files to the `multi-line comment
   <https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting>`_
   applies only to Linux, not to U-Boot. Only large hunks which are copied
@@ -23,6 +24,82 @@ The following rules apply:
   <https://peps.python.org/pep-0008/>`_. Use `pylint
   <https://github.com/pylint-dev/pylint>`_ for checking the code.
 
+Code Formatting with clang-format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+U-Boot provides a `.clang-format` configuration file that was copied directly
+from the Linux kernel without any modifications, ensuring complete compatibility
+with kernel coding standards. Here are common ways to use clang-format:
+
+**Basic usage for single files:**
+
+.. code-block:: bash
+
+   clang-format -style=file -i <file>
+
+**Format multiple files:**
+
+.. code-block:: bash
+
+   find . -name '*.c' -o -name '*.h' | xargs clang-format -style=file -i
+
+**Integration with git (format only staged changes):**
+
+.. code-block:: bash
+
+   git clang-format
+
+**Editor integration examples:**
+
+* **Vim/Neovim:** Install vim-clang-format plugin
+* **Emacs:** Use clang-format.el
+* **VSCode:** Install "Clang-Format" extension
+* **Most IDEs:** Have built-in or plugin support for clang-format
+
+The `.clang-format` file in the repository root ensures consistent formatting
+across the entire codebase and aligns with Linux kernel coding standards.
+
+**Disabling clang-format for specific code blocks:**
+
+In some cases, you may want to disable automatic formatting for specific code
+sections, such as carefully formatted tables, assembly code, or imported code
+from other projects. Use the following comments to control formatting:
+
+.. code-block:: c
+
+   // clang-format off
+   static const struct register_config regs[] = {
+       { 0x1000, 0x12345678 },  // Base address register
+       { 0x1004, 0xabcdef00 },  // Control register
+       { 0x1008, 0x00000001 },  // Status register
+   };
+   // clang-format on
+
+**Controversial aspects of coding style enforcement:**
+
+Coding style enforcement can be controversial, and it's difficult to have one
+configuration that satisfies everyone's personal preferences. The goal of using
+clang-format is consistency across the codebase rather than accommodating
+individual preferences. While some developers may disagree with specific
+formatting choices, maintaining a uniform style throughout the project makes
+code more readable and maintainable for the entire development community.
+
+**Best practices for formatting:**
+
+When using clang-format to format code, consider these best practices:
+
+* **Format only changed blocks:** It's preferred to format only the blocks of
+  code that have been modified rather than entire files. This keeps diffs
+  focused on actual changes and makes code reviews easier.
+
+* **Separate formatting commits:** If you need to format entire files, create
+  a separate commit containing only formatting changes. This allows reviewers
+  to easily distinguish between functional changes and pure formatting updates.
+
+* **Use git clang-format:** The ``git clang-format`` command is particularly
+  useful as it formats only the lines that have been modified in your current
+  changes, avoiding unnecessary formatting of unchanged code.
+
 * Use patman to send your patches (``tools/patman/patman -H`` for full
   instructions). With a few tags in your commits this will check your patches
   and take care of emailing them.