Differences

This shows you the differences between two versions of the page.

--- design:coding_style_guide [2025/05/04 16:48] – [Global identifiers] asie
+++ design:coding_style_guide [2025/05/05 15:17] (current) – [Commenting] asie
@@ Line 27: / Line 27: @@
     * For example, ''ws_system_is_color_active'', not ''ws_system_color_active''.
   * Some macros can refer to a type; for readability and to distinguish it from function categories, these should be //suffixed//.
-    * For example, an I/O port will be referred to as ''WS_DISPLAY_BORDER_PORT'', and a mask for ''WS_DISPLAY_BORDER_COLOR(c)'' will be referred to as ''WS_DISPLAY_BORDER_COLOR_MASK''.
+    * For example, an I/O port will be referred to as ''WS_DISPLAY_BORDER_PORT'', and a mask for ''%%WS_DISPLAY_BORDER_COLOR(c)%%'' will be referred to as ''WS_DISPLAY_BORDER_COLOR_MASK''.
-===== Code formatting =====
+===== Code style =====
+  * Braces are always on the same line, and are separated with a space.
+  * If it doesn't otherwise hurt readability, using no braces for a single-line statement is fine.
 <code c>
@@ Line 38: / Line 41: @@
     if (multi_line) {
         braces_on_the_same_line(1);
+        braces_on_the_same_line(2);
-        // ... but treat sizeof, etc. like a function.
-        memcpy(&b, &a, sizeof(a));
     }
 }
 </code>
-===== Commenting =====
+  * Pointers are declared with the asterisk ''*'' adjacent to the type name. ''const'' goes before the type name.
+<code c>
+const void __far *return_pointer(void __far *my_pointer);
+</code>
+===== Documentation =====
 Use [[https://www.doxygen.nl/manual/docblocks.html|Doxygen-compatible]] formatting for all user-facing documentation comments:
@@ Line 51: / Line 58: @@
   * Javadoc-style ''%%/** .. */%%'' blocks for documenting functions, types, macros and/or where larger comment blocks are warranted;
   * For one-line comments, such as on enumerated types, ''%%///<%%'' can be used.
+  * When writing internal header macros/functions that are not meant for the library user, put such code between ''%%/// @cond INTERNAL%%'' and ''%%/// @endcond%%'' blocks.
 ===== Best practices =====