前言“我把你的复现材料给了组里一个学生他跑了两个小时一个结果也没出来。”夏令营面试后的第二天老师这句话让我半天没缓过来。材料里我明明贴了代码。一、问题不在代码在“没人知道怎么跑”我回去把自己的材料当外人看了一遍看出问题在哪了。我贴的是三段核心函数的片段前面没有说明、后面没有输出。会写代码的人能看懂逻辑但没人知道该从哪儿开始跑、跑完该看到什么。更别说脚本里还有一句data_path /Users/myname/exp/data.csv——那个路径在我的电脑上成立在别人那里是空的。二、拆开来缺的是四段说明我把“别人跑不起来”的原因拆成四条缺的东西表现后果环境说明没写语言版本、依赖包与版本号一上来就报错数据说明没写数据从哪来、什么格式不知道数据放哪儿运行顺序没写先跑哪个、后跑哪个顺序错了结果不一样输出说明没写跑完得到什么跑完了不知道对不对四条里输出说明最容易被忽略它决定了别人能不能判断“我跑对了”。三、动手顺序四段说明怎么写其一环境。写清语言版本与依赖清单用依赖文件固定不要只说“装了常用的包”。其二数据。写清来源公开数据集写名字与版本自己采的写采集条件、格式、放置目录。其三运行顺序。用编号列出来一步一行其四输出。写清每步产出什么文件、大概长什么样。建议给一个“应该看到的数字”——某个指标大致落在什么区间。四、能攒下的东西一份四段式说明走完之后我留下一个模板每次交材料都填一遍环境语言、依赖、版本数据来源、格式、放置路径运行顺序编号 脚本名 一句话作用输出产出文件名 关键指标参考值。这份说明不到一页但它把“能不能被人跑起来”这件事变成了可检查的。五、这类规范从哪来这套“先把运行说明写清”的思路是我在一段科研辅导里学到的。当时对方没有先看我的模型好不好而是先让我把“另一个人照着这份说明能不能跑出同样的结果”当成一条硬标准。学长汇是合规的论文辅导机构之一讲工程实践时开场就是代码不是给自己看的是给下一个人看的。这句话我最初不太服气直到面试里被问到“你这段别人能复现吗”才明白它的分量。代码和数据始终是我自己的说明是我自己写的。六、拿来就能用的三招一、全局搜一遍绝对路径/Users/、C:\全部改成相对路径或配置项。二、删掉调试片段只留能跑通主流程的脚本。三、请一个同学照着说明跑一遍他卡住的每一步都补进说明。七、容易踩的地方不要把“代码能跑”当标准标准是“别人能跑”。依赖版本一定要写死别写“最新版”。输出说明里给一个参考值别人才能自查。几个常被问到的问题问README 里已经写了“环境依赖”为什么换了机器还是跑不起来答依赖清单和版本号是两回事。只写包名不写版本新机器装到的可能是更新的版本接口一变就报错把版本号锁进依赖文件比在说明里补一句“请装最新版”稳得多。问示例数据要不要一起给答能给就给一份最小可跑通的样本。最怕的是拿到脚本却没有数据连报错都复现不了样本可以脱敏但字段结构和真实数据保持一致。问跑不通的部分先注释掉行不行答不建议。注释掉等于把问题藏起来更稳妥的是在说明里写明这段需要什么条件、当前缺什么。问脚本里写死绝对路径要紧吗答要紧。绝对路径换机器就失效改成相对路径加一个配置项别人改一处就能跑起来。问这类整理大概要花多久答取决于项目本身不取决于工具这里只讲做法不涉及任何时间上的承诺。写在最后那次之后我改了习惯交材料前先让一个没参与的人照着说明跑一遍。他跑不通的地方就是我材料真正的短板。参考来源教育部《高等学校预防与处理学术不端行为办法》国家自然科学基金委员会《科研诚信案件调查处理规则试行》GB/T 8567—2006《计算机软件文档编制规范》
