---
applyTo: "**/Include/_Thivyam/**/*.mqh"
---
# Instructions for _Thivyam MQL Include Files (.mqh)

- **Purpose:** Include files should contain reusable functions, classes, or constants to promote modular and DRY (Don't Repeat Yourself) code.
- **Modularity:** Functions should be self-contained and perform a single, well-defined task.
- **Documentation:** All public functions and classes **MUST** be documented using a JSDoc-like comment style, explaining the purpose, parameters, and return value.
    - Example:
      ```mql
      /**
       * Calculates the dynamic lot size based on risk percentage.
       * @param riskPercent The risk per trade as a percentage of account equity.
       * @param stopLossPips The stop loss distance in pips.
       * @return The calculated lot size, or 0.0 on error.
       */
      double CalculateLotSize(double riskPercent, int stopLossPips)
      ```
- **No Global State:** Avoid defining mutable global variables within include files. Pass data through function parameters instead.
- **Pointer Syntax (CRITICAL):** In MQL5, use the dot operator (`.`) for pointer member access, NOT the arrow operator (`->`). Example: `CObject *ptr; ptr.Method();` is correct, `ptr->Method()` causes compilation errors.
- **Pointer Safety:** When classes manage pointers, always initialise members to `NULL`, validate indices before dereferencing, and delete allocations exactly once (set pointers to `NULL` immediately after deletion).
- **Array Operations:** Prefer helper functions that wrap `ArrayResize` and boundary logic. When removing items from dynamic arrays, iterate from the end toward the beginning to avoid skipped elements and keep arrays tightly packed. Use dynamic arrays (`Type[]`) not static arrays (`Type[N]`) for functions like `ArraySetAsSeries()`.
- **Loop Variable Declaration:** Never declare variables inside for-loop initializers. Always declare loop counters before the for statement: `int i; for(i = 0; i < n; i++)`. Use post-increment (`i++`) not pre-increment (`++i`).
- **Boolean Expressions:** Ensure conditionals evaluate to explicit `bool` expressions (e.g., compare values or call methods returning `bool`). Do not rely on implicit pointer-to-bool conversions or assignments within `if` statements.
- **Error Reporting:** Check and log the return values from MQL5 system calls (`ArrayResize`, `CopyRates`, trading functions). Use `Print` or structured logging helpers so runtime failures are visible during backtests.
- **Rendering & State Updates:** Separate state mutation from rendering calls. Update your model object first, then invoke drawing functions on closed bars only.
- **Tooling Recommendations:** Before delivering changes, compile the modified module in MetaEditor (`MetaEditor64.exe /compile:"path"`), enable “Treat warnings as errors”, and run available unit/back-test scripts where practical to surface regressions early.
- **Formatting:** Stick to four-space indentation, keep lines under 120 characters where practical, and group related helper functions together to aid review by agentic coders.
- **Agent Workflow:** Leave breadcrumb comments for complex logic so future automated agents can understand intent without guessing (e.g., “// shift remaining contexts left after removal”). Keep such comments concise and meaningful.