Pale Red Dot Dev Log #2
Three working Python scripts—NASA API access, PDS label parsing, coordinate transforms—sat in a folder. They worked. They had comments. And they were about to become a maintenance problem.
The issue: standalone scripts capture what code does, but not why. The reasoning, alternatives considered, surprises encountered—all of that lived in conversation logs, not in the artifacts themselves.
For this project, a different approach seemed worth trying: treating Jupyter notebooks as the primary exploration artifact.
The Tradeoff with Scripts
Exploratory code naturally starts as scripts. Quick, disposable, answering “does this work?” But once they work, they tend to become permanent—while the context that produced them fades.
Comments help, but they’re secondary to the code. Separate documentation drifts out of sync. Neither captures the narrative of discovery.
Notebooks as Executable Notes
A notebook can serve as notes that happen to run.
The markdown cells explain what’s being explored and why. The code cells demonstrate. The output proves it works. When the question “how does CAHVOR projection work again?” arises later, the notebook answers directly—no separate document to locate.
This doesn’t suit every project. For Pale Red Dot, where the exploration is much of the value, it fits.
Separating Narrative from Machinery
Notebooks shouldn’t contain everything. Complex functions interrupt the narrative; readers coming for understanding don’t need implementation details inline.
A workable separation:
- Notebooks: the story—what, why, what was learned
- Modules: the machinery—reusable functions, data structures, algorithms
- Notebooks import modules, keeping code cells short
Module docstrings explain usage. Notebooks show purpose.
Doctests as Synchronization
Operations demonstrated in notebooks can become doctests in modules:
# In notebook:
gale = MarsCoordinate(lat=-4.5895, lon=137.4417)
print(gale.to_planetographic())
# Same operation in module doctest
This keeps documentation and tests aligned with actual usage.
Resulting Structure
pale-red-dot/
├── notebooks/ # Exploration AND documentation
│ ├── 01_pds_archive_access.ipynb
│ ├── 02_pds_labels_and_cahvor.ipynb
│ └── 03_coordinate_systems.ipynb
├── src/palereddot/ # Reusable modules with doctests
│ ├── pds.py
│ ├── cahvor.py
│ └── coordinates.py
Each notebook tells a story. Each module provides tools. They evolve together.
When This Applies
This pattern suits projects where understanding matters as much as code: scientific computing, data analysis, technical education, anything requiring explanation later.
The restructuring cost about two hours on top of the original scripting work. Whether that investment pays off depends on how often the artifacts get revisited—for a multi-phase project like this one, it likely will.
Part of an ongoing series on building Pale Red Dot, a browser-based Mars surface viewer.