applying-code-standards

Applying Code Standards

Review checklist for ensuring analysis code meets quality standards for maintainability and reproducibility. Covers project structure, readability, reproducibility, and documentation.

---

Required Output Files (MANDATORY)

Your analysis MUST include these files. Do not consider the analysis complete without them:

1. config.py - All parameters with rationale comments explaining each threshold
2. requirements.txt - Pinned dependency versions (e.g., pandas==2.0.3)
3. README.md - Setup and usage instructions

---

Checklist

Copy this checklist and track progress:

Code Quality Review:
- [ ] Project structure
- [ ] Readability
- [ ] No unnecessary duplication
- [ ] Configuration is explicit
- [ ] Inputs are validated
- [ ] Reproducibility
- [ ] Documentation
- [ ] Housekeeping

---

Guidelines

1. Project Structure

• ALWAYS maintain a clean, consistent directory layout
• Separate exploratory work (notebooks, helper scripts) from production code (modules)
• Treat raw data as immutable — never overwrite originals
• ALWAYS create requirements.txt with the python version (echo "# "$(python --version) >> requirements.txt) and pinned versions (pip freeze >> requirements.txt) to capture the software environment for reproducibility.

Required: requirements.txt example:

# Python 3.13.2
pandas==2.0.3
numpy==1.24.0

2. Readability

• A program should not require readers to hold more than a handful of facts in memory at once
• Make names consistent, distinctive, and meaningful (functions, variables, files)
• Make code style and formatting consistent
• Keep functions small and focused — each should do one thing well
• Do not comment and uncomment sections of code to control behavior; use configuration instead
• Avoid hardcoded paths: use pathlib and relative paths or environment variables
• Keep data loading, processing, analysis, and visualization in distinct stages

3. No Unnecessary Duplication