nhexen/rules-sqf icon
public
Published on 4/27/2025
SQF Coding Rules

Rules
## Build & Development Commands
- Use official tools like Arma 3 Tools or Mikero's Tools to package addons into PBO files.
- Always use an appropriate prefix for your addons to avoid naming conflicts with other mods.
- For quick compilation, use the command `MakePbo FolderName` to automatically produce a PBO file in the parent directory.
- Ensure your `config.cpp` is correctly set up at the root of your addon folder so the game can recognize your content.
- Use tools like `armake` to automate PAA conversion, binarization, and PBO creation tasks.
- Organize your functions in `CfgFunctions` to allow preloading and compilation at mission startup.

## Testing Guidelines
- Use SQFvm or similar tools to run unit tests without launching the full game, saving development time.
- Test scripts in a controlled environment before integrating them into a full mission.
- Use available SQF interpreters for syntax checking and static code analysis.
- Create test scenarios that validate all conditional branches of your code.
- Use simple and explicit test variables to make debugging easier.
- Test your code in different contexts: singleplayer, hosted multiplayer, and dedicated multiplayer servers.

## Code Style & Guidelines
- Be consistent in your code formatting. Choose an indentation style and stick to it throughout your project.
- Use spaces before and after braces to improve readability.
- Use either two/four spaces or a tab for indentation, but do not mix both.
- Name your variables and functions meaningfully; avoid names like `_u` in favor of `_uniform`.
- Use camelCase for your variables (e.g., `myVariable`, `playerObject`, `initialPosition`).
- Make your variables `private` using the `private` keyword or `params` to avoid accidental overwrites.
- Prefix public variables with your tag to avoid conflicts with other mods.
- End every SQF expression with a semicolon (`;`), not just a line break.
- For complex nested conditionals, prefer using `switch` over multiple `if` statements.
- Use comments to explain the "why" rather than the "how" of your code.

## Documentation Guidelines
- Document each function with a clear description of its purpose, parameters, and return value.
- Use block comments (`/* comment */`) for function documentation and line comments (`// comment`) for inline explanations.
- Follow a consistent structure for function documentation: name, author, description, parameters, return value, examples.
- Clearly indicate dependencies between your scripts and functions to aid maintainability.
- Document any potential side effects of your functions (global changes, object creation, etc.).
- For complex projects, create a `README.md` file explaining your mod's structure and installation.
- Include usage examples for every public function you create.
- Clearly document prerequisites and known incompatibilities with other mods.