Docs

2026-06-18 14:59:21 -05:00
parent 6135d60ddc
commit 730a5b2b10
17 changed files with 2825 additions and 415 deletions
@@ -0,0 +1,382 @@
+# Coding Style
+
+All source is C11. Everything below is derived from the existing codebase — match it exactly.
+
+---
+
+## File structure
+
+### Headers (`.h`)
+
+```c
+/**
+ * Copyright (c) 2026 Dominic Masters
+ * 
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "direct/dependency.h"
+```
+
+- `#pragma once` always, never `#ifndef` guards.
+- No blank line between the license block and `#pragma once`.
+- One blank line between `#pragma once` and the first `#include`.
+
+### Sources (`.c`)
+
+```c
+/**
+ * Copyright (c) 2026 Dominic Masters
+ * 
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "thisfile.h"
+#include "assert/assert.h"
+#include "util/memory.h"
+```
+
+- First include is always the matching `.h` for this `.c` file.
+- Remaining includes follow with no separator unless logically grouped (then one blank line between groups — see [Include order](#include-order)).
+
+---
+
+## Include order
+
+In `.c` files, include in this order with a blank line between each group:
+
+1. The matching header (e.g. `#include "entity.h"`)
+2. Core utilities (`assert/assert.h`, `util/memory.h`, `util/math.h`, etc.)
+3. Engine subsystems (`display/...`, `input/...`, etc.)
+4. Domain subsystems (`rpg/...`, `scene/...`, etc.)
+
+In `.h` files, only include what the header directly requires. Never include more than necessary to make the type definitions in that header compile.
+
+All include paths are relative to `src/dusk/` (the root include directory). Use the full path:
+```c
+#include "rpg/overworld/map.h"   // correct
+#include "map.h"                  // wrong
+```
+
+---
+
+## Line length
+
+80-character limit. Break before it, not after.
+
+Multi-parameter function signatures break one param per line, with 2-space indent, closing `)` on its own line before `{`:
+
+```c
+errorret_t textureInit(
+  texture_t *texture,
+  const int32_t width,
+  const int32_t height,
+  const textureformat_t format,
+  const texturedata_t data
+) {
+```
+
+Same rule for calls that don't fit on one line:
+
+```c
+assertTrue(
+  data.paletted.palette->count ==
+  mathNextPowTwo(data.paletted.palette->count),
+  "Palette color count must be a power of 2"
+);
+```
+
+---
+
+## Indentation and spacing
+
+- **2 spaces** per indent level. No tabs.
+- No space between a control keyword and its `(`:
+  ```c
+  if(x) {        // correct
+  if (x) {       // wrong
+  ```
+- No space between a function name and its `(` in either declarations or calls.
+- Opening brace on the same line:
+  ```c
+  void entityUpdate(entity_t *entity) {
+  if(x) {
+  for(int i = 0; i < n; i++) {
+  ```
+- Closing brace always on its own line, except `} else {` and `} while(...)`.
+- One blank line between function definitions in `.c` files.
+- No trailing whitespace.
+
+---
+
+## Naming
+
+| Kind | Convention | Example |
+|---|---|---|
+| Types (struct/union/typedef) | `snake_case_t` | `entity_t`, `worldpos_t` |
+| Struct tags | `struct name_s` | `struct entity_s` |
+| Union tags | `union name_u` | `union texturedata_u` |
+| Enum tags (when typedef'd separately) | `name_enum_t` | `entitytype_enum_t` |
+| Functions | `subsystemVerb` (camelCase, noun-first) | `entityInit`, `mapGetTile` |
+| Macro constants | `UPPER_SNAKE_CASE` | `CHUNK_WIDTH`, `FIXED_ONE` |
+| Function-like macros | `camelCase` (same as functions) | `errorThrow`, `assertNotNull` |
+| Global subsystem instances | `UPPER_SNAKE_CASE` | `ENGINE`, `MAP`, `ENTITIES` |
+| Local variables | `camelCase` | `tileNew`, `spriteCount` |
+| Parameters | `camelCase` | `texture`, `worldPos` |
+
+Subsystem prefix always comes first in function names: `textureInit`, `shaderBind`, `spriteBatchFlush`. The verb describes the action: `Init`, `Update`, `Dispose`, `Get`, `Set`, `Is`, etc.
+
+---
+
+## Typedefs
+
+### Structs
+
+```c
+typedef struct {
+  uint8_t id;
+  entitytype_t type;
+} entity_t;
+```
+
+Use a named tag (`struct entity_s`) only when forward declaration is required:
+
+```c
+typedef struct entity_s {
+  // ...
+} entity_t;
+```
+
+### Unions
+
+```c
+typedef union texturedata_u {
+  struct {
+    uint8_t *indices;
+    palette_t *palette;
+  } paletted;
+  color_t *rgbaColors;
+} texturedata_t;
+```
+
+### Enums
+
+When the enum values need to be a compact integer (common for arrays and flags), declare the enum separately and typedef an integer type:
+
+```c
+typedef enum {
+  ENTITY_TYPE_NULL,
+  ENTITY_TYPE_PLAYER,
+  ENTITY_TYPE_NPC,
+  ENTITY_TYPE_COUNT
+} entitytype_enum_t;
+
+typedef uint8_t entitytype_t;  // actual type used everywhere
+```
+
+Always include `_NULL` as the first value (zero) and `_COUNT` as the last value.
+
+---
+
+## `#define` constants
+
+All-caps, underscores. Wrap multi-token expressions in parentheses:
+
+```c
+#define CHUNK_WIDTH 16
+#define CHUNK_HEIGHT CHUNK_WIDTH
+#define CHUNK_TILE_COUNT (CHUNK_WIDTH * CHUNK_HEIGHT * CHUNK_DEPTH)
+```
+
+Multi-line macros: backslash continuation, body indented 2 spaces, closing line has no backslash:
+
+```c
+#define errorThrow(message, ...) \
+  return errorThrowImpl(\
+    &ERROR_STATE, ERROR_NOT_OK, __FILE__, __func__, __LINE__, (message), \
+    ##__VA_ARGS__ \
+  )
+```
+
+---
+
+## `const` usage
+
+Mark every pointer and value parameter `const` unless the function modifies it:
+
+```c
+void entityTurn(entity_t *entity, const entitydir_t direction);
+errorret_t textureInit(texture_t *texture, const int32_t width, ...);
+```
+
+`entity_t *entity` is non-const because the function writes to it; `direction` is const because it is read-only.
+
+---
+
+## `void` in no-argument functions
+
+Use `(void)` in definitions and declarations of zero-parameter functions:
+
+```c
+errorret_t engineUpdate(void);
+errorret_t spriteBatchFlush(void);
+```
+
+---
+
+## Global subsystem state
+
+Each subsystem exposes a single global instance declared `extern` in the header and defined (once) in the `.c` file:
+
+```c
+// entity.h
+extern entity_t ENTITIES[ENTITY_COUNT];
+
+// entity.c
+entity_t ENTITIES[ENTITY_COUNT];
+```
+
+Never define a subsystem global as `static` in a header.
+
+---
+
+## Assertions
+
+Place assertions at the very top of a function, before any logic:
+
+```c
+void entityInit(entity_t *entity, const entitytype_t type) {
+  assertNotNull(entity, "Entity pointer cannot be NULL");
+  assertTrue(type < ENTITY_TYPE_COUNT, "Invalid entity type");
+  // ... actual logic
+}
+```
+
+Available assertion macros (from `assert/assert.h`):
+- `assertNotNull(ptr, msg)`
+- `assertNull(ptr, msg)`
+- `assertTrue(expr, msg)`
+- `assertFalse(expr, msg)`
+- `assertUnreachable(msg)`
+- `assertStringEqual(a, b, msg)`
+- `assertIsMainThread(msg)` / `assertNotMainThread(msg)`
+
+---
+
+## Error handling style
+
+Functions that can fail return `errorret_t`. Three patterns:
+
+```c
+// Propagate a child call's failure and return from this function:
+errorChain(someCall());
+
+// Return success:
+errorOk();
+
+// Return failure:
+errorThrow("Descriptive message %s", variable);
+```
+
+`errorChain` is used inline — do not capture the result first:
+```c
+errorChain(textureInitPlatform(texture, width, height, format, data));  // correct
+errorret_t r = textureInitPlatform(...); errorChain(r);                 // wrong
+```
+
+---
+
+## Struct initialization
+
+Use C99 designated initializers for any struct literal with more than one field:
+
+```c
+static const entitycallback_t ENTITY_CALLBACKS[ENTITY_TYPE_COUNT] = {
+  [ENTITY_TYPE_NULL] = { NULL },
+
+  [ENTITY_TYPE_PLAYER] = {
+    .init = playerInit,
+    .movement = playerInput
+  },
+};
+```
+
+```c
+shadermaterial_t material = {
+  .unlit = {
+    .color = COLOR_WHITE,
+    .texture = NULL
+  }
+};
+```
+
+---
+
+## Fixed-size array iteration
+
+Prefer pointer arithmetic with `do/while` over index loops for iterating through fixed global arrays:
+
+```c
+entity_t *ent = ENTITIES;
+do {
+  if(ent->type == ENTITY_TYPE_NULL) continue;
+  // ...
+} while(++ent, ent < &ENTITIES[ENTITY_COUNT]);
+```
+
+Use `for` loops when an index variable is actually needed.
+
+---
+
+## Comments
+
+Comments explain *why*, not *what*. One short inline comment is fine; multi-line block comments for non-obvious invariants only.
+
+```c
+// Walking up a ramp — only the direction the ramp faces is valid.
+if(tileIsRamp(tileCurrent) && ...) {
+```
+
+Section labels inside long functions are acceptable:
+
+```c
+// Chunks
+{
+  ...
+}
+
+// Entities
+{
+  ...
+}
+```
+
+Doc comments on public functions use Javadoc style with `@param` / `@return`:
+
+```c
+/**
+ * Gets the tile at the given world position.
+ *
+ * @param position The world position.
+ * @return The tile at that position, or TILE_NULL if the chunk is unloaded.
+ */
+tile_t mapGetTile(const worldpos_t position);
+```
+
+---
+
+## Platform-conditional code
+
+Use the `DUSK_*` compile-definition macros set by `cmake/targets/<target>.cmake`:
+
+```c
+#ifdef DUSK_THREAD_PTHREAD
+  #include "thread/thread.h"
+  extern pthread_t ASSERT_MAIN_THREAD_ID;
+#endif
+```
+
+Never use `#ifdef __linux__`, `#ifdef _WIN32`, etc. directly — go through the engine macros.