MQL4/.github/instructions/mql-includes.instructions.md

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:

    /**
     * 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.