[Lldb-commits] [lldb] [lldb][Docs] Document our major differences from the LLVM style (PR #66345)
David Spickett via lldb-commits
lldb-commits at lists.llvm.org
Fri Sep 15 01:36:54 PDT 2023
https://github.com/DavidSpickett updated https://github.com/llvm/llvm-project/pull/66345
>From bcabec98725255c4abed93311d73837d09ac8dde Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Thu, 14 Sep 2023 10:05:44 +0100
Subject: [PATCH 1/2] [lldb][Docs] Document our major differences from the LLVM
style
Running:
$ clang-format -i $(find -regex "\./lldb/.*\.c") $(find -regex "\./lldb/.*\.cpp") $(find -regex "\./lldb/.*\.h")
Resulted in:
1602 files changed, 25090 insertions(+), 25849 deletions(-)
(note: this includes tests which we wouldn't format, just
using this as an example)
The vast majority of which were whitespace changes. So as far
as formatting we're not deviating from llvm for any reason
other than not churning old code.
Formatting aside, the major features of lldb (single line if,
early return) are all reflected in llvm's style. We differ mainly
on variable naming (proposed to change in https://llvm.org/docs/Proposals/VariableNames.html
anyway) and use of asserts. Which was already documented.
---
lldb/docs/resources/contributing.rst | 39 +++++++++++++++++++++-------
1 file changed, 29 insertions(+), 10 deletions(-)
diff --git a/lldb/docs/resources/contributing.rst b/lldb/docs/resources/contributing.rst
index 54917f1ce8175b3..9b133706a7fd160 100644
--- a/lldb/docs/resources/contributing.rst
+++ b/lldb/docs/resources/contributing.rst
@@ -18,19 +18,38 @@ Please refer to the `LLVM Developer Policy
authoring and uploading a patch. LLDB differs from the LLVM Developer
Policy in the following respects.
- - **Test infrastructure**: Like LLVM it is important to submit tests with your
- patches, but note that LLDB uses a different system for tests. Refer to the
- `test documentation <test.html>`_ for more details and the ``lldb/test``
- folder on disk for examples.
-
- - **Coding Style**: LLDB's code style differs from
- `LLVM's coding style <https://llvm.org/docs/CodingStandards.html>`_.
- Unfortunately there is no document describing the differences. Please be
- consistent with the existing code.
-
For anything not explicitly listed here, assume that LLDB follows the LLVM
policy.
+Coding Style
+++++++++++++
+
+LLDB's code style differs from `LLVM's coding style <https://llvm.org/docs/CodingStandards.html>`_
+in a few ways. The 2 main ones are:
+
+* `Variable naming <https://llvm.org/docs/CodingStandards.html#name-types-functions-variables-and-enumerators-properly>`_:
+ LLDB prefers variables to be ``named_like_this`` and uses the ``m_`` prefix for
+ member variables.
+
+* `Use of asserts <https://llvm.org/docs/CodingStandards.html#assert-liberally>`_:
+ See the :ref:`section below<Error Handling>`.
+
+For any other contradications please follow the existing code's style.
+
+Code in LLDB does aim to conform to clang-format but older code may not yet. As
+always, consider the `golden rule <https://llvm.org/docs/CodingStandards.html#introduction>`_
+when working with such code. Reformatting before starting work is one possible
+option.
+
+Test Infrastructure
++++++++++++++++++++
+
+Like LLVM it is important to submit tests with your patches, but note that LLDB
+uses a different system for tests. Refer to the `test documentation <test.html>`_
+for more details and the `lldb/test <https://github.com/llvm/llvm-project/tree/main/lldb/test>`_
+folder for examples.
+
+.. _Error handling:
Error handling and use of assertions in LLDB
--------------------------------------------
>From d9061c6e0389487822b90c88d4f9409bf912c368 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Fri, 15 Sep 2023 09:32:39 +0100
Subject: [PATCH 2/2] * Cleanup error handling section, remove some dead links.
* Moved lldbassert() deprecation to a note. * Show variable naming formats
using the name of the format e.g. snake_case. * Note other variable prefixes.
* Strengthen statement on clang-format. * Only refer to API tests in test
section.
---
lldb/docs/resources/contributing.rst | 58 ++++++++++++++++------------
1 file changed, 33 insertions(+), 25 deletions(-)
diff --git a/lldb/docs/resources/contributing.rst b/lldb/docs/resources/contributing.rst
index 9b133706a7fd160..5ac4afb82a0747a 100644
--- a/lldb/docs/resources/contributing.rst
+++ b/lldb/docs/resources/contributing.rst
@@ -27,27 +27,34 @@ Coding Style
LLDB's code style differs from `LLVM's coding style <https://llvm.org/docs/CodingStandards.html>`_
in a few ways. The 2 main ones are:
-* `Variable naming <https://llvm.org/docs/CodingStandards.html#name-types-functions-variables-and-enumerators-properly>`_:
- LLDB prefers variables to be ``named_like_this`` and uses the ``m_`` prefix for
- member variables.
+* `Variable and function naming <https://llvm.org/docs/CodingStandards.html#name-types-functions-variables-and-enumerators-properly>`_:
+
+ * Variables are ``snake_case``.
+
+ * Functions and methods are ``UpperCamelCase``.
+
+ * Static, global and member variables have ``s_``, ``g_`` and ``_m``
+ prefixes respectively.
* `Use of asserts <https://llvm.org/docs/CodingStandards.html#assert-liberally>`_:
See the :ref:`section below<Error Handling>`.
-For any other contradications please follow the existing code's style.
+For any other contradications, consider the
+`golden rule <https://llvm.org/docs/CodingStandards.html#introduction>`_
+before choosing to update the style of existing code.
-Code in LLDB does aim to conform to clang-format but older code may not yet. As
-always, consider the `golden rule <https://llvm.org/docs/CodingStandards.html#introduction>`_
-when working with such code. Reformatting before starting work is one possible
-option.
+All new code in LLDB should be formatted with clang-format. Existing code may
+not conform and should be updated prior to being modified. Bulk reformatting
+is discouraged.
Test Infrastructure
+++++++++++++++++++
-Like LLVM it is important to submit tests with your patches, but note that LLDB
-uses a different system for tests. Refer to the `test documentation <test.html>`_
-for more details and the `lldb/test <https://github.com/llvm/llvm-project/tree/main/lldb/test>`_
-folder for examples.
+Like LLVM it is important to submit tests with your patches, but note that a
+subset of LLDB tests (the API tests) use a different system. Refer to the
+`test documentation <test.html>`_ for more details and the
+`lldb/test <https://github.com/llvm/llvm-project/tree/main/lldb/test>`_ folder
+for examples.
.. _Error handling:
@@ -61,14 +68,13 @@ be extra thoughtful about how to handle errors. Below are a couple
rules of thumb:
* Invalid input. To deal with invalid input, such as malformed DWARF,
- missing object files, or otherwise inconsistent debug info, LLVM's
+ missing object files, or otherwise inconsistent debug info,
error handling types such as `llvm::Expected<T>
<https://llvm.org/doxygen/classllvm_1_1Expected.html>`_ or
- `std::optional<T>
- <https://llvm.org/doxygen/classllvm_1_1Optional.html>`_ should be
- used. Functions that may fail should return their result using these
- wrapper types instead of using a bool to indicate success. Returning
- a default value when an error occurred is also discouraged.
+ ``std::optional<T>`` should be used. Functions that may fail
+ should return their result using these wrapper types instead of
+ using a bool to indicate success. Returning a default value when an
+ error occurred is also discouraged.
* Assertions. Assertions (from ``assert.h``) should be used liberally
to assert internal consistency. Assertions shall **never** be
@@ -90,16 +96,18 @@ rules of thumb:
behaves like ``assert()``. When asserts are disabled, it will print a
warning and encourage the user to file a bug report, similar to
LLVM's crash handler, and then return execution. Use these sparingly
- and only if error handling is not otherwise feasible. Specifically,
- new code should not be using ``lldbassert()`` and existing
- uses should be replaced by other means of error handling.
+ and only if error handling is not otherwise feasible.
+
+.. note::
+
+ New code should not be using ``lldbassert()`` and existing uses should
+ be replaced by other means of error handling.
* Fatal errors. Aborting LLDB's process using
``llvm::report_fatal_error()`` or ``abort()`` should be avoided at all
- costs. It's acceptable to use `llvm_unreachable()
- <https://llvm.org/doxygen/Support_2ErrorHandling_8h.html>`_ for
- actually unreachable code such as the default in an otherwise
- exhaustive switch statement.
+ costs. It's acceptable to use ``llvm_unreachable()`` for actually
+ unreachable code such as the default in an otherwise exhaustive
+ switch statement.
Overall, please keep in mind that the debugger is often used as a last
resort, and a crash in the debugger is rarely appreciated by the
More information about the lldb-commits
mailing list