From cdca339ac2b4c65673e52ddbbecd439aa65cba54 Mon Sep 17 00:00:00 2001 From: Jonas Devlieghere Date: Thu, 30 Oct 2025 14:30:17 -0700 Subject: [PATCH 1/3] [GitHub] Add Copilot review instructions for LLDB This is an experiment to encode the LLVM Coding Standards [1] as instructions for the Copilot reviewer on GitHub. Ideally, this will catch common issues automatically and reduce the review burden. Adding Copilot as a reviewer is entirely opt-in. Initially, I will add it as a reviewer to test this. If the experiment is successful, we can explore how to integrate this into other parts of LLVM. [1]: https://llvm.org/docs/CodingStandards.html --- .github/instructions/lldb.instructions.md | 76 +++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 .github/instructions/lldb.instructions.md diff --git a/.github/instructions/lldb.instructions.md b/.github/instructions/lldb.instructions.md new file mode 100644 index 0000000000000..450b02ba009c0 --- /dev/null +++ b/.github/instructions/lldb.instructions.md @@ -0,0 +1,76 @@ +--- +applyTo: lldb/**/* +--- + +When reviewing code, focus on: + +## Language, Libraries & Standards + +- Target C++17 and avoids vendor-specific extensions. +- For Python scripts, follow PEP 8 formatting and use tools like `black` or `darker`. +- Prefer standard library or LLVM support libraries instead of reinventing data structures. + +## Comments & Documentation + +- Each source file should include the standard LLVM file header. +- Header files must have proper header guards. +- Non-trivial classes and public methods should have Doxygen documentation. +- Use `//` or `///` comments normally; avoid block comments unless necessary. + +## Language & Compiler Issues + +- Write portable code; wrap non-portable code in interfaces. +- Do not use RTTI or exceptions. +- Prefer C++-style casts over C-style casts. +- Avoid static constructors or global objects with heavy initialization. +- Use `class` or `struct` consistently; `struct` only for all-public data. + +## Headers & Library Layering + +- Include order: module header → local/private headers → project headers → system headers. +- Headers must compile standalone (include all dependencies). +- Maintain proper library layering; avoid circular dependencies. +- Include minimally; use forward declarations where possible. +- Keep internal headers private to modules. +- Use full namespace qualifiers for out-of-line definitions. + +## Control Flow & Structure + +- Prefer early exits over deep nesting. +- Avoid `else` after `return`, `continue`, `break`, or `goto`. +- Encapsulate loops that compute predicates into helper functions. + +## Naming + +- LLDB's code style differs from LLVM's coding style. +- Variables are `snake_case`. +- Functions and methods are `UpperCamelCase`. +- Static, global and member variables have `s_`, `g_` and `m_` prefixes respectively. + +## General Guidelines + +- Use `assert` liberally; prefer `llvm_unreachable` for unreachable states. +- Avoid `using namespace std;` in headers. +- Ensure at least one out-of-line virtual method per class with virtuals. +- For `switch` on enums, omit `default` to catch missing cases. +- Prefer range-based `for` loops. +- Capture `end()` outside loops if not using range-based iteration. +- Use LLVM’s `raw_ostream` instead of ``. +- Avoid `std::endl`; use `\n` unless flushing is needed. +- Methods in class definitions are already inline—don’t add `inline`. + +## Microscopic Details + +- Preserve existing style in modified code. +- Prefer pre-increment (`++i`) when value is unused. +- Omit braces for single-statement `if`, `else`, `while`, `for` unless needed. + +## Review Style + +- Be specific and actionable in feedback. +- Explain the "why" behind recommendations. +- Link back to the LLVM Coding Standars: https://llvm.org/docs/CodingStandards.html. +- Ask clarifying questions when code intent is unclear. + +Remember that these standards are **guidelines**. Always prioritize consistency +with the style that is already being used by the surrounding code. From 804c9309966d43b7534089db660b54462906f52d Mon Sep 17 00:00:00 2001 From: Jonas Devlieghere Date: Thu, 30 Oct 2025 15:14:00 -0700 Subject: [PATCH 2/3] Fix typo and don't mention tools like black and darker --- .github/instructions/lldb.instructions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/instructions/lldb.instructions.md b/.github/instructions/lldb.instructions.md index 450b02ba009c0..8615992c2d706 100644 --- a/.github/instructions/lldb.instructions.md +++ b/.github/instructions/lldb.instructions.md @@ -6,8 +6,8 @@ When reviewing code, focus on: ## Language, Libraries & Standards -- Target C++17 and avoids vendor-specific extensions. -- For Python scripts, follow PEP 8 formatting and use tools like `black` or `darker`. +- Target C++17 and avoid vendor-specific extensions. +- For Python scripts, follow PEP 8. - Prefer standard library or LLVM support libraries instead of reinventing data structures. ## Comments & Documentation From 0d165147a02cd08e6907ef8f169b76ad9766e7a9 Mon Sep 17 00:00:00 2001 From: Jonas Devlieghere Date: Thu, 30 Oct 2025 16:51:23 -0700 Subject: [PATCH 3/3] Incorporate Kristof's feedback --- .github/instructions/lldb.instructions.md | 27 +++++++++++++---------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/.github/instructions/lldb.instructions.md b/.github/instructions/lldb.instructions.md index 8615992c2d706..35bcd27b1b42f 100644 --- a/.github/instructions/lldb.instructions.md +++ b/.github/instructions/lldb.instructions.md @@ -16,14 +16,16 @@ When reviewing code, focus on: - Header files must have proper header guards. - Non-trivial classes and public methods should have Doxygen documentation. - Use `//` or `///` comments normally; avoid block comments unless necessary. +- Non-trivial code should have comments explaining what it does and why. Avoid comments that explain how it does it at a micro level. ## Language & Compiler Issues - Write portable code; wrap non-portable code in interfaces. - Do not use RTTI or exceptions. - Prefer C++-style casts over C-style casts. -- Avoid static constructors or global objects with heavy initialization. +- Do not use static constructors. - Use `class` or `struct` consistently; `struct` only for all-public data. +- When then same class is declared or defined multiple times, make sure it's consistently done using either `class` or `struct`. ## Headers & Library Layering @@ -37,7 +39,7 @@ When reviewing code, focus on: ## Control Flow & Structure - Prefer early exits over deep nesting. -- Avoid `else` after `return`, `continue`, `break`, or `goto`. +- Do not use `else` after `return`, `continue`, `break`, or `goto`. - Encapsulate loops that compute predicates into helper functions. ## Naming @@ -50,27 +52,28 @@ When reviewing code, focus on: ## General Guidelines - Use `assert` liberally; prefer `llvm_unreachable` for unreachable states. -- Avoid `using namespace std;` in headers. -- Ensure at least one out-of-line virtual method per class with virtuals. -- For `switch` on enums, omit `default` to catch missing cases. -- Prefer range-based `for` loops. +- Do not use `using namespace std;` in headers. +- Provide a virtual method anchor for classes defined in headers. +- Do not use default labels in fully covered switches over enumerations. +- Use range-based for loops wherever possible. - Capture `end()` outside loops if not using range-based iteration. -- Use LLVM’s `raw_ostream` instead of ``. -- Avoid `std::endl`; use `\n` unless flushing is needed. -- Methods in class definitions are already inline—don’t add `inline`. +- Including `` is forbidded. Use LLVM’s `raw_ostream` instead. +- Don’t use `inline` when defining a function in a class definition. ## Microscopic Details - Preserve existing style in modified code. - Prefer pre-increment (`++i`) when value is unused. +- Use `private`, `protected`, or `public` keyword as appropriate to restrict class member visibility. - Omit braces for single-statement `if`, `else`, `while`, `for` unless needed. ## Review Style - Be specific and actionable in feedback. - Explain the "why" behind recommendations. -- Link back to the LLVM Coding Standars: https://llvm.org/docs/CodingStandards.html. +- Link back to the LLVM Coding Standards: https://llvm.org/docs/CodingStandards.html. - Ask clarifying questions when code intent is unclear. -Remember that these standards are **guidelines**. Always prioritize consistency -with the style that is already being used by the surrounding code. +Ignore formatting and assume that's handled by external tools like `clang-format` and `black`. +Remember that these standards are **guidelines**. +Always prioritize consistency with the style that is already being used by the surrounding code.