vibe-research-coding

name	vibe-research-coding
description	Best practices for writing elegant, readable research code - direct implementations, locality of behavior, fail-fast, strict size limits, clean separation of experiment and plotting code. Use whenever writing or refactoring code in a research project, creating new experiment scripts, or organizing a source tree.

Elegant Coding

Best practices for research code: readability over abstraction. Every constraint here shares one premise: the user reads all of this code. None of it applies to directories the user never reads (such as data/ and tmp/).

Base style

• KISS + YAGNI: write the most direct implementation; no generic utilities, no future-proofing.
• Locality of Behavior: keep related logic together. A 60-line function that clearly mirrors a formula's steps beats a 10-file inheritance chain.
• Code reads like the algorithm: the main loop should read like the steps of the math it implements. Someone who knows the method should recognize it in the code at a glance.
• Plain beats clever: never use tricks that defeat reading or static analysis (exec or dynamic attribute creation, global-state closures, type-sniffing branches), even when the plain version is longer.
• No dead code: no commented-out blocks kept "just in case", no leftover debug prints. Delete it; git remembers.
• Fail-fast: assert dimensions, check for NaN, crash immediately on bad data. A crash is useful debugging information. No defensive code: no meaningless try/except or if/else fallbacks.
• All code comments in English.

Structure

• The top level of src/ holds experiment entry scripts only; reusable components go into semantically named packages.
• Experiments within a project follow one uniform structure (entry script → training/compute module → results directory → plotting module): the first experiment that takes shape is the model for all later ones. No freelancing.
• Keep experiment code and plotting code separate: the experiment computes and writes its data to disk; plotting is a separate script that reads that data. Changing a figure then never requires re-running the experiment, and the data behind every figure is guaranteed to exist on disk. Entry scripts carry no --replot-style switches. Careful: do not git-track very large output files.
• Keep a clean boundary between evaluation code and the system it evaluates: a scorer must never be imported by the thing it scores. When judge and judged are entangled, the evaluation cannot be trusted.

Reproducibility pitfalls

• A fixed random seed does not mean reproducible: on CUDA, torch.manual_seed alone is not enough; explicit determinism settings (cudnn deterministic, etc.) are required. Measured fact: the same seed can diverge by ten orders of magnitude within a few hundred steps.

Size limits (so the user can read a file in one sitting and scan a folder at a glance)

• Keep each file to ~200 lines or fewer; split or abstract beyond that. Exception: files that purely enumerate similar items (parameter tables, formula lists) have no limit.
• Keep each folder to ~7 code files or fewer; beyond that, create semantically named subfolders as a Python package. The intent of this rule is scannability, not the number itself. It does not apply to folders the user never reads.
• The failure mode to avoid is the god-file: a 1000-plus-line class holding 200-line methods, with plotting, training, and bookkeeping all fused together. One concept per small file; separate concerns instead of fusing them.