path: root/doc/CODING_STYLE.md

# Coding Style Examples

Detailed examples for the project's C++ coding style.

---

## Core Rules Examples

### Const Placement
```cpp
const T* name  // Correct
const T *name  // Wrong
```

### Pre-Increment
```cpp
++x  // Correct
x++  // Wrong (except when postfix needed)
```

### Operator Spacing
```cpp
x = (a + b) * c;  // Correct - spaces around all operators
x=(a+b)*c;        // Wrong - no spaces
```

### No Auto (except complex iterators)
```cpp
int count = get_count();              // Correct
auto count = get_count();             // Wrong

for (auto it = map.begin(); ...)      // OK - complex iterator type
```

### No C++ Casts
```cpp
(int)value                            // Correct
static_cast<int>(value)               // Wrong
```

---

## Preprocessor Style

```cpp
#if defined(MY_TAG)
  // code here
#endif /* defined(MY_TAG) */
```

Always use `defined()` and closing comment.

---

## Platform-Specific Code

**Rule:** Platform-specific compilation (`#ifdef DEMO_CROSS_COMPILE_WIN32`, etc.) must be confined to `src/gpu/gpu.{h,cc}` and `src/platform/platform.{h,cc}`.

### Correct
```cpp
// In gpu.h - abstract platform differences
#if defined(DEMO_CROSS_COMPILE_WIN32)
using GpuTextureCopyInfo = WGPUImageCopyTexture;
#else
using GpuTextureCopyInfo = WGPUTexelCopyTextureInfo;
#endif

// In effect.cc - use abstraction
GpuTextureCopyInfo src_copy = {
    .texture = src, .mipLevel = 0, .origin = {0, 0, 0}};
```

### Wrong
```cpp
// In effect.cc - direct platform check (FORBIDDEN)
#if defined(DEMO_CROSS_COMPILE_WIN32)
  WGPUImageCopyTexture src_copy = {...};
#else
  WGPUTexelCopyTextureInfo src_copy = {...};
#endif
```

**Rationale:**
- Centralizes platform handling in gpu/platform layers
- Prevents #ifdef proliferation across codebase
- Makes cross-platform testing easier

---

## Struct Initialization

### Good
```cpp
const WGPUDescriptor desc = {
  .format = g_format,
  .dimension = WGPUTextureViewDimension_2D,
};
```

### Bad
```cpp
WGPUDescriptor desc = {};
desc.format = g_format;
desc.dimension = WGPUTextureViewDimension_2D;
```

Use designated initializers, not field-by-field assignment.

---

## Control Flow Braces

**Rule:** Multi-line `for` or `if` statements must use curly braces.

### Good
```cpp
for (int i = 0; i < 10; ++i) {
  do_something(i);
}
```

### Bad
```cpp
for (int i = 0; i < 10; ++i)
  do_something(i);
```

---

## Class Keywords Indentation

```cpp
class MyClass {
 public:   // 1 space indent
  void foo();

 private:  // 1 space indent
  int field_;
};
```

---

## Comments

### Function Comments
```cpp
// Initializes the audio engine with default settings.
void audio_init() {
  ...
}
```

One-line comment for non-obvious functions.

### File Headers
```cpp
// demo64k - 64 kilobyte demo
// src/audio/synth.cc
// Audio synthesis engine
```

Three-line header for all source files.

---

## WGSL Shader Style

### Always Use ShaderComposer (Required)

**Rule:** Always load `.wgsl` shaders via `ShaderComposer::Get().Compose(...)`, even if the shader has no `#include` directives. Never pass the raw shader string directly to `wgpuDeviceCreateShaderModule`.

```cpp
// Correct
const std::string src = ShaderComposer::Get().Compose({}, my_shader_wgsl);
WGPUShaderSourceWGSL wgsl_src = {};
wgsl_src.code = str_view(src);

// Wrong - bypasses #include resolution
wgsl_src.code = str_view(my_shader_wgsl);
```

**Rationale:** Shaders may gain `#include` directives later; bypassing `ShaderComposer` silently breaks them at runtime with no compile error.

---

### File Header (Required)

Every `.wgsl` file must start with a 2-line comment header:

```wgsl
// Line 1: What the shader/snippet does (one sentence).
// Line 2: Role, main outputs, or public API surface.
```

Example:
```wgsl
// NTSC post-process effect: fisheye distortion, scanlines, and color bleeding.
// Produces a retro CRT/NTSC look using YIQ color space and C64-style dithering.
```

---


### Return vs Pointer Parameters

**Rule:** Prefer return values over pointer parameters for small structs (≤16 bytes).

```wgsl
// Correct - return value (12 bytes: 3×f32)
fn rayMarchWithID(ro: vec3<f32>, rd: vec3<f32>, init: RayMarchResult) -> RayMarchResult {
  var result = init;
  // ... modify result
  return result;
}

// Wrong - pointer parameter (unnecessary complexity)
fn rayMarchWithID(ro: vec3<f32>, rd: vec3<f32>, result: ptr<function, RayMarchResult>) {
  // ... modify *result
}
```

**Rationale:**
- Small structs (≤16 bytes) are efficiently handled by GPU return value optimization
- Functional style is clearer and less error-prone
- `ptr<function, T>` adds complexity with no performance gain for small types

### Vector and Matrix Type Aliases

**Rule:** Use concise aliases for vector and matrix types (`vec3f`, `mat4x4f`) instead of the verbose generic form (`vec3<f32>`, `mat4x4<f32>`).

```wgsl
// Correct
var p: vec3f;
var m: mat4x4f;

// Wrong
var p: vec3<f32>;
var m: mat4x4<f32>;
```

**Rationale:**
- Improves readability and reduces visual noise.
- Aligns with common graphics programming conventions.

---

## WGPU Object Initialization

**Rule:** Initialization of `WGPU...` objects should leverage `gpu.h` function helpers as much as possible.

### Correct
```cpp
// In an effect file
WGPURenderPassColorAttachment color_attachment = {};
gpu_init_color_attachment(color_attachment, output_view);
```

### Wrong
```cpp
// In an effect file
WGPURenderPassColorAttachment color_attachment = {};
color_attachment.view = output_view;
color_attachment.loadOp = WGPULoadOp_Clear;
color_attachment.storeOp = WGPUStoreOp_Store;
color_attachment.clearValue = {0.0f, 0.0f, 0.0f, 1.0f};
#if !defined(DEMO_CROSS_COMPILE_WIN32)
color_attachment.depthSlice = WGPU_DEPTH_SLICE_UNDEFINED;
#endif
```

**Rationale:**
- Centralizes platform-specific initialization logic (e.g., `depthSlice`).
- Reduces boilerplate code in effects and other rendering code.
- Ensures consistent and correct initialization across the codebase.