[lldb][Docs] Document our major differences from the LLVM style (#66345)

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.
This commit is contained in:
David Spickett 2023-09-19 08:23:00 +01:00 committed by GitHub
parent 6923a31542
commit ca723f2d40
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -18,19 +18,45 @@ 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 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, consider the
`golden rule <https://llvm.org/docs/CodingStandards.html#introduction>`_
before choosing to update the style of existing code.
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 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:
Error handling and use of assertions in LLDB
--------------------------------------------
@ -42,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
@ -71,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