一个可复用的研究代码仓库应包含代码本身，但更重要的是，它必须将代码与陌生人（或未来的你）运行、理解并信任它所需的一切打包在一起。至少，这意味着清晰的文档、可复现的环境、示例数据和许可证。
核心要素
- 结构清晰的源代码。 按功能组织模块（例如
data/、models/、utils/），并将生成图表或表格的脚本与核心逻辑分离。避免使用单一的大型笔记本；如果使用，请将关键步骤转换为.py脚本。 - 读起来像手册的README。 以2-3句话概述代码功能开头，然后列出：安装步骤、最小使用示例、预期输出，以及所附论文或报告的链接。
- 锁定文件或环境定义。 无论使用
requirements.txt、environment.yml（Conda）还是Dockerfile，都要固定每个依赖项的精确版本。这是确保六个月后研究仍可复现的关键。 - 示例输入和预期输出。 即使是一个微小的玩具数据集，也能让用户在运行完整分析前验证流程在其机器上正常工作。如果可能，包含一个带有基本单元测试的
tests/文件夹。 - 许可证文件。 如果不指定许可证，大多数用户在法律上无法重用你的代码。选择符合你意图的开源许可证（MIT、Apache 2.0 或 GPL）。
- 引用文件（CITATION.cff）。 这告诉他人如何准确引用你的工作，从而增加代码本身被引用的机会。
使其真正可复用的“加分项”
- 配置文件（例如 YAML 或 JSON），将参数与代码分离，使用户无需修改脚本即可调整设置。
- 变更日志或版本历史。 即使是简单的
CHANGELOG.md，也能帮助用户了解版本之间的变化。 - README中的简短“已知问题”部分。 坦诚说明局限性有助于建立信任。
实用工作流程
- 编写代码时，假设明天会有人在不询问你的情况下运行它。
- 在干净环境（全新的虚拟环境或容器）中测试设置。
- 添加示例数据和测试。
- 推送到公共仓库（GitHub、GitLab 或 Zenodo 以获取 DOI）。
如果你正在将代码与文献综述或论文写作一起整理，像 WisPaper 的 My Library 这样的工具可以帮助你将参考 PDF 及其元数据与项目文件夹同步——这样代码仓库就能指向正确的引用，无需你费力寻找文件。但仓库本身应始终独立：自包含、有文档、有许可证。这才是将脚本堆砌转变为可复用研究产物的关键。