Every meaningful codebase starts as a void – a .gitignore, a LICENSE, a one‑line README. Our haversine CLI calculator was no different. The initial commit (899bfcf) was almost empty: no Python files, no formulas, no tests. Just the silent promise of something to come.
That is Void Coding – the deliberate recognition that patterns do not yet exist. It is not laziness; it is humility before complexity. We knew we wanted to demonstrate the Germaneering doctrine, but we did not yet know the exact shape of the „deep code“ example. So we left space.
Phase 1: Intent Takes Shape (Specification)
Before a single line of math.sin was written, we wrote intent. Commit cc12f14 added spec.md – a declarative description of what the haversine tool should do:
- User Story 1 (P1): „A developer can calculate distance between two coordinates.“
- User Story 2 (P2): „Invalid input shows clear, educational errors.“
- User Story 3 (P3): „Output can be in miles or nautical miles.“
No framework, no algorithm, no database. Just machine‑readable objectives that an AI (or a junior engineer) could later implement. This is Intent Code: the blueprint that outlives any single implementation.
Within hours, plan.md, tasks.md, and contracts/ followed (f6fa139, 2b24f32). The intent was now executable – we could hand the spec to any developer and expect a consistent result.
Phase 2: Foundational Infrastructure
The Foundational Code pillar appeared in commits like a2a8fd5 and the .specify/ directory: bash scripts for branch management, pyproject.toml with uv integration, and a constitution.md that enforces test‑first development.
This is the substrate – the build system, the lock file, the .gitignore patterns – that outlives any single application. When the haversine tool is eventually archived, the foundation remains, ready for the next exploration.
Phase 3: Deep Code – The Haversine Formula
The climax came in commit 65721be (over 5,000 lines added). Here, the Deep Code pillar was fully realized:
- The haversine formula implemented from trigonometric primitives, not hidden behind a
pip install geopy. - Every mathematical step commented with the original equations (
a = sin²(Δφ/2) + …). - Error messages that teach geography: „Latitude must be between -90 and 90“ followed by examples of NYC (
40.7128, -74.0060) and London.
Deep Code is not about cleverness; it is about awareness beneath the abstraction. A junior developer reading this code learns spherical geometry, not just an API call.
Phase 4: Void Coding – The Unwritten Chapters
Even after the implementation, we left voids. The README’s /explorations directory is a stub – a placeholder for future essays that will extract patterns from this CLI tool. The validator.py does not yet handle altitude or 3D vectors – those are intentional gaps, waiting for a future contributor.
Void Coding is the courage to leave things undone because the pattern is not yet clear. It is the opposite of „gold plating“. In our git log, the voids are as important as the filled content.
Lessons from the Log
| Pillar | Manifestation in the Git Log | Improvement Opportunity |
|---|---|---|
| Deep Code | Inline math comments, zero dependencies, educational errors | Add --verbose flag to show intermediate steps |
| Foundational | pyproject.toml, .specify/ scripts, uv.lock | Add CI (GitHub Actions) and document scripts |
| Intent Code | spec.md, plan.md, tasks.md, contracts | Automate spec‑to‑test traceability |
| Void Coding | Empty /explorations/, missing altitude support | Create VOIDS.md to make gaps explicit |
Try It Yourself
The haversine CLI is open source. Clone the repo and run:
uv run haversine 40.7128 -74.0060 34.0522 -118.2437Then open haversine/calculator.py and see the haversine formula in plain view. That is Deep Code.
Then explore .specify/ and see the scripts that automate spec‑driven development. That is Foundational.
Read specs/001-haversine-cli/spec.md – those declarative requirements are Intent Code.
And finally, notice what is not there: the empty explorations/ folder, the missing altitude support. That is Void Coding – an invitation to you.
Contribute your own void‑filling pattern. The lab is open.