Wonderful Toolchain Wiki

User Tools

Site Tools

Trace:
design:coding_style_guide

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
design:coding_style_guide [2025/05/04 07:17] – asiedesign:coding_style_guide [2025/05/05 15:17] (current) – [Commenting] asie
Line 24: Line 24:
   * Following from that, categorizing functions should be done prefix-first, but beyond the category of the function, an operation should be written like a sentence.   * Following from that, categorizing functions should be done prefix-first, but beyond the category of the function, an operation should be written like a sentence.
     * For example, ''ws_screen_fill_tiles'' is appropriate, not ''ws_screen_tiles_fill'' or ''ws_fill_screen_tiles''.     * For example, ''ws_screen_fill_tiles'' is appropriate, not ''ws_screen_tiles_fill'' or ''ws_fill_screen_tiles''.
 +  * Predicate functions should use the verb ''is''.
 +    * 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//.   * 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> <code c>
Line 36: Line 41:
     if (multi_line) {     if (multi_line) {
         braces_on_the_same_line(1);         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> </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: Use [[https://www.doxygen.nl/manual/docblocks.html|Doxygen-compatible]] formatting for all user-facing documentation comments:
Line 49: Line 58:
   * Javadoc-style ''%%/** .. */%%'' blocks for documenting functions, types, macros and/or where larger comment blocks are warranted;   * 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.   * 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 =====
  
-===== Standards adherence =====+  * Where the size of a variable matters, use ''stdint.h'' and ''stdbool.h'' types (''int16_t'', ''uint32_t'' etc). Where the size of a variable doesn't matter, use standard C types (''int'' and ''unsigned int''). 
 +    * For 8-bit platforms, rely on ''stdint.h'' types more often; ''int'' tends to be 16-bit on those platforms, which is slower to process than ''uint8_t''. 
 +  * For functions which return a "succeeded" flag, use ''bool''. For functions which return an error code, use ''int'' and return a non-negative value on success or a negative value on failure. 
 +  * Prefer ''static inline'' functions over preprocessor macros, where applicable.
  
-For target code on most platforms, it is acceptable to depend on a feature even if it is only available in modern versions of GCC **and** Clang.+===== Target-specific notes =====
  
-Special consideration may need to be taken for platforms where the GNU/LLVM compiler is not necessarily the best open source option, such as the 8086, SM83 or Z80.+==== wswan ====
  
-===== Best practices ===== +  * We're currently limited to GCC 6.3.0 on this platform; as such, the highest available standard is ''gnu11''. 
- +  * The cost of a function call is rather high (5 bytes and 18 cycles of overhead for argument-less functions on ''wswan/medium''), and LTO is not available; as such, using ''static inline'' functions in header files for simple port I/O wrappers and similar tasks is encouraged.
-  * Where the size of a variable matters, use ''stdint.h'' and ''stdbool.h'' types (''int16_t'', ''uint32_t'' etc). +
-    * For 8-bit platforms, rely on these more often; ''int'' tends to be 16-bit on those platforms, which is slower to process than ''uint8_t''. +
-  * For functions which return a "succeeded" flag, use ''bool''. For functions which return an error code, use ''int'' and return a non-negative value on success or a negative value on failure.+
  
 ====== References ====== ====== References ======
  
   * [[https://www.kernel.org/doc/html/latest/process/coding-style.html|Linux kernel coding style]] - served as a source of inspiration   * [[https://www.kernel.org/doc/html/latest/process/coding-style.html|Linux kernel coding style]] - served as a source of inspiration
design/coding_style_guide.1746343022.txt.gz · Last modified: by asie