1.  Experimenting with Code

Before using AI to help write code you need a place to run and measure code quickly. This chapter sets up a scratch arena — a lightweight, disposable workspace where experiments are cheap, failure is expected, and anything worth keeping gets promoted to a real project.

Why isolate experiments?

1. Real projects carry pressure: tests must pass, CI must be green, code review is watching. A scratch arena has none of that friction.
2. Separating “trying something” from “building something” keeps both cleaner — the real project stays stable while experiments fail fast.
3. A version-controlled scratch space lets you revisit a dead end without losing it, and compare two approaches side by side.
4. Measuring code from the start — lines, complexity, timing — builds the habit of treating metrics as feedback, not bureaucracy.

1.1  Arena Layout

A flat directory at the root of your workspace gives each language its own folder. The metrics/ and notes/ folders accumulate output and observations across sessions.

sandbox/
  rust/        ← cargo workspace, or cargo new per experiment
  cpp/         ← single-file programs; no CMake needed for scratch
  csharp/      ← dotnet new console -o scratch; reuse between runs
  python/      ← flat scripts; one .venv at this level
  metrics/     ← tokei and code_metrics output, saved per session
  notes/       ← scratchpad.md, one entry per session

Quick project init per language:

## Rust
cargo new scratch && cd scratch
cargo run

## C++  (no project file needed for single-file experiments)
g++ -std=c++23 -Wall -o out main.cpp && ./out

## C#
dotnet new console -o scratch && cd scratch
dotnet run

## Python  (Windows; use forward slash on macOS/Linux)
python -m venv .venv
.venv\Scripts\activate
python script.py
python -i script.py     # run then drop into REPL with all names live

1.2  Code Metrics

Metrics tools answer “how big?” and “how complex?” before and after a change. Run them at the start of a session to establish a baseline, and after each significant change to see what moved. code_metrics.py (in track) — Reports line counts, function counts, and blank/comment ratios per file. Good for tracking growth of a scratch project over sessions. tokei — Cross-language line counter; breaks down by language and file type. Run at the sandbox root to see the whole arena at a glance.
cargo install tokei scc (Sloc Cloc and Code) — Like tokei but adds estimated complexity and cost columns. Useful when comparing equivalent programs across languages.
cargo install scc radon (Python) — Cyclomatic complexity and maintainability index per function.
pip install radon  —  run: radon cc -s script.py cargo clippy (Rust) — Catches non-obvious mistakes and style issues that the compiler misses. Treat warnings as a quality signal, not a failure condition. cppcheck (C++) — Static analysis for undefined behavior, memory issues, and style.
cppcheck --enable=all main.cpp

1.3  Performance and Timing

hyperfine — Cross-language wall-clock benchmarker. Runs a command N times, warms the cache, and reports mean ± stddev with outlier detection. Use it to compare the same algorithm across languages directly.

cargo install hyperfine
hyperfine './out input.txt' 'python script.py input.txt'

tf_timer.py / pa_timer.py (in track) — Purpose-built timing wrappers for TextFinder and PageValidator. Model these for any experiment that needs repeated-run averaging. Python cProfile (built-in) — Function-level profiler; no install needed. Pairs with snakeviz (see section 1.4) for visual output.
python -m cProfile -s cumtime script.py cargo flamegraph (Rust) — Generates a flame graph SVG showing where CPU time actually goes. Requires perf (Linux) or DTrace (macOS); works in WSL on Windows.
cargo install flamegraph BenchmarkDotNet (C#) — Add as a NuGet package; annotate methods with [Benchmark]. Produces statistically rigorous tables with warmup and GC stats.

1.4  Visualizers

CodeWebifier (in track) — Converts source files to syntax-highlighted HTML for display in the site. Run it on any experiment worth keeping to publish it. snakeviz (Python) — Browser-based flame graph for cProfile output.

pip install snakeviz
python -m cProfile -o out.prof script.py
snakeviz out.prof           # opens browser with interactive flame graph

graphviz / dot — Renders dependency graphs, state machines, and call graphs as SVG. Most build tools can emit .dot format (cargo metadata, doxygen).
winget install graphviz cargo doc --open (Rust) — Not just for publishing — generated doc pages are the fastest way to browse the public API of any crate you add to an experiment. VS Code extensions worth installing for the arena:

• Error Lens — inline error messages next to the offending line
• GitLens — last-edit blame inline; useful for tracking what changed in scratch
• CodeMetrics (kisstkondoros) — per-function complexity score in the editor gutter
• Rust Analyzer — essential for Rust; includes inlay type hints
• clangd — C++ language server with inline diagnostics and completions

1.5  A Typical Session Flow

A short ritual at the start and end of each session keeps the arena useful:

1. Create or reset the scratch project for today’s language.
2. Write the simplest version that compiles and runs (15–20 lines max).
3. Run metrics: tokei and code_metrics.py for a baseline snapshot.
4. Iterate: change one thing, re-run, compare metrics and timing.
5. If the result is worth keeping, run CodeWebifier and move it to a named folder; otherwise delete and move on.
6. Add one line to notes/scratchpad.md: what you tried, what you learned.

1.6  References

Resource	Description
hyperfine	Cross-platform benchmarking tool for command-line programs.
tokei	Fast, accurate code line counter with language breakdown.
scc	Line counter with complexity and estimated cost columns.
radon	Python complexity metrics: cyclomatic complexity, maintainability index.
cargo flamegraph	Flame graph profiler for Rust programs.
BenchmarkDotNet	Rigorous microbenchmark framework for .NET.
snakeviz	Browser-based viewer for Python cProfile output.