# 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.

---

## 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

### 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