判断一份代码本是否合格，有一个比“字段填全了吗”更可靠的办法：把原问卷设计者请出会议室，让另一位分析者只拿数据文件和代码本，复算报告中的一个指标。如果他无法判断分母、把“未展示”当成“不满意”，或者不知道某个综合分怎样生成，这份代码本仍然依赖原作者脑中的隐性知识。
因此，代码本不是导出表格旁边的一张中英文对照表，而是问卷语义、数据结构与分析口径之间的版本化合同。它既要让人知道变量代表什么，也要让程序知道哪些值合法、哪些记录适用、怎样从原始字段复算派生结果。题目很多时不必一开始采用复杂的元数据标准，但这三层关系不能缺失。
先看一份只有六个变量的数据为什么仍会被误读
假设一项功能体验调查导出以下变量：respondent_id、used_feature、sat_feature、reason_1、reason_2、sat_top2。单看名称，分析者仍无法确定满意度是五点还是十分制、多选项中的零代表“未选择”还是“未看到”、综合指标是否包含“不知道”，更无法知道功能满意度只向实际使用者展示。
一份可用的变量级代码本至少要把这六个变量解释成下面这样：
| 变量 | 来源与适用对象 | 取值或计算 | 分析提醒 |
|---|---|---|---|
used_feature | Q3，所有完成筛选者 | 1=过去30天使用；0=未使用；-8=不知道 | -8 不得并入“未使用” |
sat_feature | Q4，仅 used_feature=1 | 1=非常不满意至5=非常满意；-7=拒答 | 有效分母是看到 Q4 且给出1至5的人 |
reason_1 | Q5 多选拆分，仅低满意者 | 1=选择“响应慢”；0=展示但未选；空=未展示 | 空值与0具有不同含义 |
sat_top2 | 由 Q4 派生 | Q4为4或5记1，1至3记0，其余为空 | 公式版本1.1；不含特殊缺失 |
这里最重要的并不是表格长什么样，而是每个字段同时回答四件事：它来自哪里、谁有机会产生值、每个值表示什么、分析时允许怎样使用。ICPSR 对代码本的说明也强调，代码本描述数据集合的内容、结构和布局，变量层应包含变量名、标签、完整题文、实际取值和值标签；缺失数据的含义同样需要记录。
代码本需要研究级、文件级和变量级三层信息
研究级信息解释数据为何产生：研究目的、目标总体、收集时间、模式、抽样与招募方式、问卷语言、同意与访问条件、负责人以及建议引用方式。缺了这一层，变量即使定义准确，也可能被外推到错误人群或错误时期。
文件级信息解释拿到的文件是什么：一行代表受访者、一次作答还是一次事件；主键与关联键是什么；文件包含原始数据、清洗数据还是公开脱敏数据；字符编码、日期时区、宽表或长表结构如何；它对应哪个问卷与处理脚本版本。多轮追踪或问卷加访谈时，还要写清文件之间怎样连接。
变量级信息才是多数人熟悉的数据字典：稳定变量名、简短标签、完整题文与提示、题目版本、数据类型、单位、参考期、选项代码、量表方向、适用总体、跳转条件、特殊缺失、清洗规则和派生公式。国际数据文档联盟的DDI-Codebook把研究、数据文件、变量和问题放在同一描述体系中，还覆盖来源、处理、质量控制、访问与相关材料。这说明代码本不是孤立的“列说明”，而是数据出处和处理历史的一部分。
团队不一定需要立即输出 DDI XML，但可以借用它的层级思路：先把研究与文件背景定住，再解释每个变量。否则一张有数百列的表会很详细，却仍回答不了“这些数据代表谁”。
缺失值不能只用一个空白表示
问卷数据中的空白至少可能来自四种过程：受访者因跳转逻辑从未看到该题；看到了但主动跳过或拒绝；选择“不知道”；作答过程中断。还有一种缺失来自后处理，例如原值不合法而被设空。它们对应不同的分母和偏差风险，压成同一个空值后很难恢复。
以上面的功能满意度为例，未使用功能的人属于结构性不适用，不能进入满意度分母；使用者看到题目后拒答属于项目缺失，应报告缺失规模；在到达该题前退出属于单元未完成，可能提示失访偏差。若公开文件因隐私规则屏蔽小群体，还应使用另一种代码，避免分析者把披露控制误认成没有记录。
实际设计中可以为特殊状态保留负数代码，也可以保留原始空值并增加缺失原因字段。选择哪一种并非关键，关键是原始数据、代码本和分析脚本使用同一规则。不要让“拒答=-7”在下个项目里突然变成“逻辑未展示”，也不要把特殊缺失参与均值计算。
多选、随机呈现、权重和派生变量要写到能复算
多选题通常会拆成多个二元变量，或保存在一张“受访者—选项”长表中。代码本必须说明存储方式、是否限制选择数量、选项是否随机、零与空白的区别，以及“其他”文本放在哪里。如果问卷中途增加一个选项，还要标出它从哪个版本开始可见，不能把早期样本的未展示当成未选择。
随机化与版本分流应保留随机组、显示顺序、文案版本和实验单元。只保存最终答案，会让顺序效应和不同文案混在一起。即使这些字段不出现在普通报告里，它们仍是解释异常差异和复核实验的必要元数据。
权重变量不能只标注“最终权重”。至少说明目标分布、参与校准的变量、截尾或缩放处理、适用总体、权重均值与范围，以及由哪个脚本版本生成。不同分析若使用不同权重，应分别命名并说明用途。权重可以调整已知维度的不平衡，不能自动修复未知的覆盖和无回答偏差。
派生变量要留下源变量、过滤条件、公式、特殊缺失处理、舍入规则和版本。例如“满意用户占比”应写成 Q4 等于4或5的人数，除以 Q4 有效回答人数；不是一句“由满意度计算”。复杂指标最好附可执行代码或伪代码，并用几个已知输入输出作为单元测试。
变量名称要稳定，但含义变化时不能假装连续
用 q12 作为变量名便于对照页面，却会在插题、删题和多语言版本中漂移。更稳妥的名称可以表达构念与参考期，例如 feature_use_30d、feature_sat_5pt。题号保留在单独的“问卷位置”字段中，变量名用于跨版本追踪。
稳定并不意味着永远复用同一变量。可以用一个变更矩阵决定：
- 只修改错别字、展示样式，测量含义不变：保留变量名，增加展示版本。
- 参考期从30天改为90天、量表从五点改为七点：创建新变量，说明不可直接拼接。
- 选项新增但核心问题不变：保留主问题版本，同时记录每个选项的可用起始版本。
- 派生公式或权重方法改变：保留旧结果，创建新版本并记录重算范围，不能覆盖历史口径。
代码本本身也要有版本号、更新时间、维护者和变更说明。问卷发布时生成初版，预测试后更新；正式回收开始后冻结题目与代码映射；清洗和派生阶段再增加处理信息。让代码本随数据产生，比项目结束后凭记忆补文档可靠得多。
用“盲交接”而不是字段数量验收
交付前，请一位没有参与问卷设计的同事只依赖数据、代码本和指定脚本完成五项任务：
- 说出每一行代表什么，并找到稳定主键；
- 计算功能满意度的有效分母，解释为什么未使用者不进入；
- 区分多选题中的“未选”和“未展示”；
- 用原始变量复算一个派生指标，并与交付结果对上；
- 指出本文件对应的问卷版本、收集时间和允许外推的人群。
任何一步需要口头询问原作者，就把答案补回代码本或关联材料。若两位分析者得到不同基数，不要先争论哪张图正确，先找出合同中缺失的规则。真正的验收标准是可独立解释和复算，而不是有多少列被填写。
在问卷派的工作流中，题目文本、选项、显示逻辑和回收批次可以成为代码本的初始来源，团队还需补齐研究总体、业务定义、清洗决定、派生公式与版本责任。工具可以导出字段，却不能替团队决定“不知道”是否属于有效回答，也不能判断一次量表改动是否破坏趋势。把这些判断留下，数据才不会在离开原作者之后迅速失去意义。