domains / research / empirical-coding-standards / coding-guidelines

coding-guidelines

Skill card

combined

The two skills share the name 'coding-guidelines' but address completely different domains and languages. The first (actionbook/rust-skills) provides specific Rust language conventions (naming, memory, concurrency, async). The second (brycewang-stanford/Auto-Empirical-Research-Skills) provides project structure and coding standards for empirical research using Python and Stata. They do not overlap in content, so one is not a reproduction of the other. Combining them creates a comprehensive skill for a researcher who might use both Rust (for performance-critical data processing) and Python/Stata (for analysis and reporting).

Repositories

Other copies

Combined skill

---
name: coding-guidelines
description: "Use when establishing coding standards for empirical research projects involving Rust, Python, or Stata. Covers project structure, language-specific best practices, and reproducibility."
---

# Empirical Research Coding Guidelines

This skill defines standards for empirical research projects. It covers project organization, Python/Stata analysis workflows, and Rust performance-critical components.

## 1. Project Structure (Research Standard)

Use the following directory structure for all empirical projects:

```
ProjectName/
├── Code/
│   ├── [Number]_[Name].py         # Data processing (Python)
│   ├── AN_[Number]_[Name].do      # Analysis scripts (Stata)
│   ├── AN_[Number]_[Name].py      # Analysis scripts (Python)
│   ├── LogFiles/                  # Stata log files
│   └── README.md                  # Project documentation
├── Data/
│   ├── Raw/                       # Original data (never modify)
│   ├── Intermediate/              # Partial processing
│   └── Clean/                     # Analysis-ready data
└── Results/
    ├── Tables/                    # Regression tables
    └── Figures/                   # Visualizations
```

**Script Numbering:**
- `0`: Initial data extraction
- `1a, 1b`: Data cleaning
- `2a, 2b`: Data merging
- `3a, 3b`: Feature engineering
- `AN_1, AN_2`: Formal analysis

## 2. Python Guidelines (Analysis & Data Processing)

### Path Management
Always use relative paths from the project root for portability:

```python
from pathlib import Path

def get_project_root():
    return Path(__file__).parent.absolute()

base_dir = get_project_root()
data_clean_dir = base_dir / ".." / "Data" / "Clean"
```

### Script Template
Include a docstring with input/output files, author, and date. Use `main()` function pattern.

### Data Handling
- Use `pandas` for data manipulation.
- Always validate input files exist before processing.
- Log progress with clear section headers and record counts.

## 3. Stata Guidelines (Econometrics)

- Use `reghdfe` for panel regressions.
- Use `outreg2` or `esttab` for regression tables.
- Save logs to `Code/LogFiles/`.

## 4. Rust Guidelines (Performance-Critical Components)

If using Rust for data processing or high-performance tasks, adhere to these core rules:

### Naming
- No `get_` prefix: `fn name()` not `fn get_name()`.
- Iterators: `iter()`, `iter_mut()`, `into_iter()`.
- Conversions: `as_` (cheap), `to_` (expensive), `into_` (ownership).

### Data Types & Memory
- Use newtypes for domain semantics (e.g., `struct Email(String)`).
- Pre-allocate: `Vec::with_capacity()`.
- Use `Cow<str>` for potentially modified borrowed data.
- Meaningful lifetimes: `'src`, `'ctx`.

### Error Handling
- Use `?` for propagation.
- Use `expect()` over `unwrap()` when value is guaranteed.
- Use `thiserror`/`anyhow` for error types.

### Concurrency & Async
- Use atomics for primitive types, not `Mutex`.
- Do not hold locks across `await` points.
- Use `parking_lot::Mutex` over `std::sync::Mutex` where appropriate.

## 5. General Best Practices

- **Reproducibility:** All scripts must be runnable from the project root without hardcoded absolute paths.
- **Documentation:** Public functions and modules must have docstrings/comments.
- **Versioning:** Track data versions in `Data/` subdirectories.