From 47b6253049b54186663b4205d3441f88656dc22e Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Mon, 2 Feb 2026 16:12:09 +0100
Subject: flesh out extra details in the MD files

---
 TODO.md                     | 17 +++++++++++++++++
 doc/CONTRIBUTING.md         | 29 +++++++++++++++++++++++++++++
 src/tests/test_3d_render.cc | 14 ++++++++------
 3 files changed, 54 insertions(+), 6 deletions(-)

diff --git a/TODO.md b/TODO.md
index 3f74c80..8d5d3b4 100644
--- a/TODO.md
+++ b/TODO.md
@@ -25,6 +25,23 @@ This file tracks the next set of immediate, actionable tasks for the project.
            == etc.
     - [ ] the inclusion of gpu.h (either "gpu.h" or <webgpu/gpu.h>) seems to be a recurring compilation and portability issue. Can we have a single inclusion of gpu.h in some platform header instead of scattered inclusion in .cc files? This would reduce the single-point-of-compilation failures during compilation and portability checks.
 
+-   ** Task #?: platform-specific code hygiene
+    There's several platform-specific code scattered over several source files (.cc and .h)
+    For instance:
+```cpp
+#if defined(DEMO_CROSS_COMPILE_WIN32)
+#include <webgpu/webgpu.h>
+#else
+#include <webgpu.h>
+#endif /* defined(DEMO_CROSS_COMPILE_WIN32) */
+```
+    This sort of code should be gathered at once single place (platform.h?) once for all.
+    - [ ] => Make all cross-compile and platform-specific conditional code sit in one single header file.
+
+-   ** Task #?: platform_init() should return a PlatformState directly instead of taking a PlatformState& parameter to write into
+    - [ ] maybe incorporate the platform time (platform_get_time()) into the PlatformState directly during platform_poll() call?
+    - [ ] same with aspect_ratio (platform_get_aspect_ratio()) unless it's not an invariant and the function needs to be called each time
+
 ## Future Goals
 
 -   **Task #5: Implement Spectrogram Editor**
diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md
index 265b686..13be092 100644
--- a/doc/CONTRIBUTING.md
+++ b/doc/CONTRIBUTING.md
@@ -94,6 +94,8 @@ if variable_name is not mutated afterward.
 Also: pass parameter as "const ref" as much as possible
 (```const Struct& param``` instead of pointers or non-const refs)
 
+In summary: use 'const variable = ...;` as much as possible.
+
 ### put spaces around code and operators (cosmetics)
 
 Don't compact the code to much horizontally, and prefer adding extra
@@ -169,6 +171,33 @@ private:
   int field_;
 ```
 
+### try to use per-field initialized const struct
+
+Use the `.field = ...,` initialization pattern instead for `var.field =
+...;`, especially if it means you can have the variable be declared 'const'
+that way.
+
+Example, instead of:
+```cpp
+WGPUTextureViewDescriptor view_desc = {};
+view_desc.format = g_format;
+view_desc.dimension = WGPUTextureViewDimension_2D;
+view_desc.mipLevelCount = 1;
+view_desc.arrayLayerCount = 1;
+```
+
+use:
+```cpp
+const WGPUTextureViewDescriptor view_desc = {
+  .format = g_format,
+  .dimension = WGPUTextureViewDimension_2D,
+  .mipLevelCount = 1,
+  .arrayLayerCount = 1,
+};
+```
+
+Make sure the `.field = ...,` initialization pattern is compatible with the compiler / c++ version used.
+
 ### vertical space
 
 keep the code compact vertically. That includes shader code, too.
diff --git a/src/tests/test_3d_render.cc b/src/tests/test_3d_render.cc
index e8a6bf1..3084edc 100644
--- a/src/tests/test_3d_render.cc
+++ b/src/tests/test_3d_render.cc
@@ -246,12 +246,14 @@ int main(int argc, char** argv) {
     wgpuSurfaceGetCurrentTexture(g_surface, &surface_tex);
     if (surface_tex.status ==
         WGPUSurfaceGetCurrentTextureStatus_SuccessOptimal) {
-      WGPUTextureViewDescriptor view_desc = {};
-      view_desc.format = g_format;
-      view_desc.dimension = WGPUTextureViewDimension_2D;
-      view_desc.mipLevelCount = 1;
-      view_desc.arrayLayerCount = 1;
-      WGPUTextureView view =
+      const WGPUTextureViewDescriptor view_desc = {
+        .format = g_format,
+        .dimension = WGPUTextureViewDimension_2D,
+        .mipLevelCount = 1,
+        .arrayLayerCount = 1,
+      };
+
+      const WGPUTextureView view =
           wgpuTextureCreateView(surface_tex.texture, &view_desc);
       g_renderer.render(g_scene, g_camera, time, view);
       wgpuTextureViewRelease(view);
-- 
cgit v1.2.3