more

CONVENTIONS.md

@@ -10,6 +10,7 @@ This document outlines the strict C style and architectural conventions expected
     *   Float: `F4`, `F8`
     *   Boolean: `B1`, `B2`, `B4`, `B8` (use `true`/`false` primitives)
     *   Strings/Chars: `UTF8` (for characters), `Str8` (for string slices)
+*   **Fundamental Type Casts:** Strictly use the provided casting macros (e.g., `u8_(val)`, `u4_r(ptr)`, `s4_(val)`) instead of standard C-style cast syntax like `(U8)val`. Standard casts should only be used for complex types or when an appropriate macro isn't available.
 *   **WinAPI Structs:** Only use `MS_` prefixed fundamental types (e.g., `MS_LONG`, `MS_DWORD`) *inside* WinAPI struct definitions (`MS_WNDCLASSA`, etc.) to maintain FFI compatibility. Do not use them in general application logic.
 
 ## 2. Declaration Wrappers & X-Macros
@@ -18,8 +19,8 @@ This document outlines the strict C style and architectural conventions expected
     *   `typedef Enum_(UnderlyingType, Name) { ... };`
 *   **X-Macros:** Use X-Macros to tightly couple Enums with their corresponding string representations or metadata.
     ```c
-    #define My_Tag_Entries() 
-            X(Define, "Define") 
+    #define My_Tag_Entries() \
+            X(Define, "Define") \
             X(Call,   "Call")
     ```
 
@@ -43,19 +44,16 @@ This document outlines the strict C style and architectural conventions expected
         } 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.
+*   **Conditionals & Control Flow:** Always place `else if` and `else` statements on a new line. Align control flow parentheses (e.g., between consecutive `while` and `if` blocks) vertically when possible for aesthetic uniformity:
+    ```c
+    while (len < 8) len ++;
+    if    (len > 0) { ... }
+    ```
+*   **Address-Of Operator:** Do insert a space between the address-of operator (`&`) and the variable name.
+    *   **Correct:** `& my_var`
+    *   **Incorrect:** `&my_var`
 
 ## 5. Memory Management
 *   **Standard Library:** The C standard library is linked, but headers like `<stdlib.h>` or `<string.h>` should not be included directly. Required functions should be declared manually if needed, or accessed via compiler builtins.
@@ -77,3 +75,4 @@ This document outlines the strict C style and architectural conventions expected
                 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`).
+