adjustments

CONVENTIONS.md

@@ -32,7 +32,29 @@ This document outlines the strict C style and architectural conventions expected
 
 ## 4. Formatting & Layout
 *   **Vertical Alignment:** Align related variable declarations, struct fields, and function prototypes into columns to create a "sheet-like" layout. This improves visual parsing.
-*   **Brace Style:** Use Allman style (braces on a new line) for function bodies control block (`if`, `for`, `switch`, etc.) that spans more than 50 lines or contains nested logic.
+    *   Example Struct:
+        ```c
+        typedef struct MS_WNDCLASSA {
+            U4          style;
+            S8          (*lpfnWndProc)(void*, U4, U8, S8);
+            S4          cbClsExtra;
+            // ...
+            char const* lpszClassName;
+        } MS_WNDCLASSA;
+        ```
+*   **Multi-line Argument Alignment:** For long function signatures, place one argument per line with a single 4-space indent.
+    *   Example:
+        ```c
+        WinAPI B4 ms_read_console(
+            MS_Handle handle, 
+            UTF8*r    buffer, 
+            U4        to_read, 
+            U4*r      num_read, 
+            U8        reserved_input_control
+        ) asm("ReadConsoleA");
+        ```
+*   **WinAPI Grouping:** Group foreign procedure declarations by their originating OS library (e.g., Kernel32, User32, GDI32) using comment headers.
+*   **Brace Style:** Use Allman style (braces on a new line) for function bodies or control blocks (`if`, `for`, `switch`, etc.) that are large or complex. Smaller blocks may use K&R style.
 *   **Conditionals:** Always place `else if` and `else` statements on a new line, un-nested from the previous closing brace.
 
 ## 5. Memory Management
@@ -45,3 +67,13 @@ This document outlines the strict C style and architectural conventions expected
     *   **Correct:** `char const* my_ptr;` (Pointer to a constant character)
     *   **Correct:** `U4 const* const my_ptr;` (Constant pointer to a constant U4)
     *   **Incorrect:** `const char* my_ptr;`
+
+## 7. Metadata Coupling (X-Macros)
+*   **Metadata Enums:** Use X-Macros to define Enums that are tightly coupled with static metadata (colors, prefixes, names).
+    *   Example:
+        ```c
+        #define Tag_Entries() \
+                X(Define,  "Define",  0x0018AEFF, ":") \
+                X(Call,    "Call",    0x00D6A454, "~")
+        ```
+*   **Naming Conventions:** When using X-Macros for Tags, entry names should be PascalCase, and the Enum symbols should be prefixed with the Enum type name (e.g., `tmpl(STag, Define)` -> `STag_Define`).