From 4caa5d8fc4bb0ee015d6d76102ca4e3cf86bc63e Mon Sep 17 00:00:00 2001 From: LagoLunatic Date: Sun, 23 Aug 2026 14:29:44 -0400 Subject: [PATCH] Add CONTRIBUTING.md, update coding guidelines --- CONTRIBUTING.md | 5 +++++ README.md | 2 ++ docs/coding_guidelines.md | 26 +++++++++++++++++++------- docs/decompiling.md | 4 +++- 4 files changed, 29 insertions(+), 8 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..6cc0080c6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,5 @@ +# Contributing + +Anyone can open a pull request, but please be aware that we do not accept contributions that are primarily AI-generated or directly copy-pasted from Ghidra. Your PR will be closed if it contains obvious signs of machine-generated code. It is your responsibility to check the code that you are submitting and make sure it is readable and feels like something a human programmer would write. Refer to the [coding guidelines page](coding_guidelines.md) for more information. + +Check the [readme](/README.md) for details on how to get the repository set up, and the [decompiling guide](/docs/decompiling.md) for an explanation of the process of decompiling itself. diff --git a/README.md b/README.md index c2c93ea28..8dcc9502f 100644 --- a/README.md +++ b/README.md @@ -121,3 +121,5 @@ Contributing ======= If you've got all the requirements set up and want to learn how to contribute to the decompilation effort, see [this guide](/docs/decompiling.md) for details. + +Anyone can open a pull request, but please be aware that we do not accept contributions that are primarily AI-generated or directly copy-pasted from Ghidra. Your PR will be closed if it contains obvious signs of machine-generated code. It is your responsibility to check the code that you are submitting and make sure it is readable and feels like something a human programmer would write. Refer to the [coding guidelines page](coding_guidelines.md) for more information. diff --git a/docs/coding_guidelines.md b/docs/coding_guidelines.md index 9711ab88f..e8050b6ba 100644 --- a/docs/coding_guidelines.md +++ b/docs/coding_guidelines.md @@ -6,13 +6,25 @@ Naming variables properly isn't required to help with the decompilation. You can ## Table of Contents -1. [Primitive types](#primitive-types) -2. [Offsets and padding](#offsets-and-padding) -3. [Includes](#includes) -4. [Naming style](#naming-style) -5. [Use the official names where possible](#use-the-official-names-where-possible) -6. [Resource archive enums](#resource-archive-enums) -7. [Look at the actor's model](#look-at-the-actors-model) +1. [Avoid Ghidra-isms](#avoid-ghidra-isms) +2. [Primitive types](#primitive-types) +3. [Offsets and padding](#offsets-and-padding) +4. [Includes](#includes) +5. [Naming style](#naming-style) +6. [Use the official names where possible](#use-the-official-names-where-possible) +7. [Resource archive enums](#resource-archive-enums) +8. [Look at the actor's model](#look-at-the-actors-model) + +## Avoid Ghidra-isms + +Try to avoid directly copy-pasting code from Ghidra without cleaning it up. Ghidra tends to produce strange code that humans wouldn't write. Some common examples include: + +- Assigning to variables inside of `if` statements using the comma operator instead of creating multiple nested `if` statements +- Always using `} else { if {` instead of `} else if {`, creating excessive indentation levels +- Placing excessive unnecessary parentheses around conditions in complex if statements, even when the code would be logically equivalent without them +- Copying the value of a variable to a second variable and checking the second variable, instead of just checking the first variable directly + +These make the code harder for a human to read, and occasionally they can even affect how the code matches in subtle ways (e.g. regalloc). ## Primitive types diff --git a/docs/decompiling.md b/docs/decompiling.md index 2b5f4f91a..8450b33e1 100644 --- a/docs/decompiling.md +++ b/docs/decompiling.md @@ -4,6 +4,8 @@ This document describes the basics how to start decompiling code and contributin If you haven't already, you should first follow the instructions in the [readme](../README.md) to get the decomp set up, as well as the tools you will be using to work on it: objdiff and Ghidra. +You should also read the [coding guidelines page](coding_guidelines.md) page to ensure that the code you write is clear and readable. + ## Table of Contents 1. [Choosing an object to decompile](#choosing-an-object-to-decompile) @@ -689,4 +691,4 @@ Then you can just submit a pull request as-is instead of worrying about it any m Once an actor is fully decompiled, you can start naming some of its member variables if you want to. This is completely optional - it's normal to submit a PR without documenting most fields. Leaving them unnamed (e.g. `field_0x290`) is preferable to coming up with wrong names if you aren't sure. -But if you do decide to start naming things, you should check out the [coding guidelines page](coding_guidelines.md). +But if you do decide to start naming things, you should check out the ['Naming style' section of the coding guidelines page](coding_guidelines.md#naming-style).