Documenting Random Seeds
You'll learn how to properly record seed values in your code and documentation so others (and future you) can reproduce your exact results.
Why Document Seeds?
Setting a seed is only half the reproducibility battle. If you don't document where and why you set seeds, your analysis becomes a black box. Imagine finding code that starts with seed=42 but no explanation—why 42? Was it arbitrary? Does changing it matter? Proper documentation turns mysterious numbers into transparent, reproducible choices.
Best Practices for Recording Seeds
In Code Comments
Always add inline comments explaining why you chose a particular seed:
# Seed ensures consistent train/test split across team runs
# Selected 2024 as project start year for easy recall
np.random.seed(2024)
X_train, X_test = train_test_split(X, y, test_size=0.2)
In Notebooks
Create a dedicated configuration cell at the top with all seeds defined as named constants:
# Reproducibility Configuration
SEED_DATA_SPLIT = 2024
SEED_MODEL_INIT = 2025
SEED_CV_FOLDS = 2026
In Documentation and Reports
Include a "Reproducibility" section that lists:
- All seed values used
- Where each seed is applied (data splitting, model initialization, cross-validation)
- The random library/version (NumPy 1.24, scikit-learn 1.3, etc.)
In Version Control
Commit messages should note when seeds change: "Updated CV seed to 2026 for consistency with new experiment protocol"
The Arbitrary Choice Problem
Seeds are inherently arbitrary—42 and 123 are equally valid. Document that you tested sensitivity to seed choice, or explicitly state it's arbitrary but fixed for consistency.
Key Takeaway: Documenting random seeds means recording not just the values, but where they're used, why they were chosen (even if arbitrary), and which libraries they affect—turning reproducible code into truly understandable science.