diff --git a/lldb/docs/resources/contributing.rst b/lldb/docs/resources/contributing.rst index 54917f1ce8175..5ac4afb82a074 100644 --- a/lldb/docs/resources/contributing.rst +++ b/lldb/docs/resources/contributing.rst @@ -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 `_ for more details and the ``lldb/test`` - folder on disk for examples. - - - **Coding Style**: LLDB's code style differs from - `LLVM's coding style `_. - 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 `_ +in a few ways. The 2 main ones are: + +* `Variable and function naming `_: + + * Variables are ``snake_case``. + + * Functions and methods are ``UpperCamelCase``. + + * Static, global and member variables have ``s_``, ``g_`` and ``_m`` + prefixes respectively. + +* `Use of asserts `_: + See the :ref:`section below`. + +For any other contradications, consider the +`golden rule `_ +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 `_ for more details and the +`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 `_ or - `std::optional - `_ 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`` 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() - `_ 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