[lldb][Docs] Document our major differences from the LLVM style

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 <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