Python实验报告写作指南：从代码附页到可复现证据链

Python实验报告这东西，十个学编程的人里至少有八个把它写成了代码附页——开头贴一大段代码，中间放一张运行结果截图，结尾写一句"运行成功，结果符合预期"，然后交上去。说实话，这种报告交了等于没交。接手的人拿到手里，只会得出一个结论：你跑通了一段代码，仅此而已。至于你理不理解这段代码、能不能解释每一步为什么要这么写、换一组数据还能不能解决同样的问题，完全看不出来。

一篇真正有用的Python实验报告，应该是一份"实验证据链"。它要证明的不是"代码能跑"，而是"你通过这个实验，得到了一个可复现、可解释、可迁移的结论"。这篇文章我会结合我带过的同学和我自己写报告的经验，从报告的定位、一次完整实验的执行过程、踩坑记录、报告内容组织，到最后怎么把实验沉淀成自己的技术资产，把一份Python实验报告从零到一拆开讲清楚。不管你是正在交作业的学生，还是刚入门、需要写技术文档的开发者，应该都能从里面找到可以直接用的东西。

1. 报告≠代码附页：一份Python实验报告究竟在证明什么

先说一个我常拿来打比方的说法：实验报告应该是菜谱，而不是"我做了这道菜"的朋友圈。菜谱要写到什么程度？别人照着你的步骤做，能做出味道差不多的菜。代码能跑、截图好看，都只是"九宫格"；真正有价值的是把环境、数据、步骤、参数、判断标准全部交代清楚，让另一个人照着走一遍，能走到同一个结果。我把报告的价值拆成三个层次，你可以拿自己的报告对一下，看它停在哪一层。

1.1 从"运行成功"到"可复现、可解释、可迁移"三个层次

第一层是可复现。别人拿到你的报告和数据，按着你写的方法步骤，能复现出一样的数字和图表。这一层很多报告就达不到，因为环境版本没写、随机种子没固定、数据编码没说明，读者一跑就报错，还以为你的结果是编的。可复现在实验报告里是底线，不是加分项。

第二层是可解释。每个关键代码块，你得说清楚它在解决什么问题。比如数据清洗实验里，为什么这里剔除缺失值而不是填充？为什么骑行时长上限设为1440分钟？这些"为什么"才是实验报告的正文，代码只是载体。很多新手写报告特别喜欢堆代码，把IDE里的东西全复制进来，但完全不解释意图，等于给了一张没有路标的路线图。

第三层是可迁移。做完这个实验，你能不能总结出一类问题的通用处理流程？比如"拿到一份带脏数据的时间序列，先查缺失、再去重、再筛异常，然后按业务口径分组对比"。如果你能从具体实验里抽象出这个流程，报告就不只是交差用的，它变成了你自己的方法论，下次换个数据源也能上手。

这三个层次，就是我在看一份实验报告时心里默认的评分尺。可复现决定报告是否可信，可解释决定报告是否有深度，可迁移决定报告是否值得保留。大多数报告死在第一层，大多数高分报告至少做到了第二层，最顶级的报告通常能到第三层——它不只是记录了一次实验，还沉淀了一类问题的解法。

1.2 实验报告、代码仓库与文档的分工

很多人觉得"反正代码都在了，报告随便写写就行"，这是把代码仓库和实验报告搞混了。代码仓库是原材料库，负责保存完整的工程文件；实验报告是加工后的成品，负责讲清楚问题、方法、证据和结论；如果再往下走一步，使用文档是给"一键运行"做的傻瓜化说明。三者服务不同场景，互相替代不了。实验报告如果变成代码的重复粘贴，它就没有存在的必要了——读者直接看仓库不就行了？

所以报告里真正要写的是代码背后的判断：哪些数据要保留、哪些要删、为什么用这个方法而不是另一个方法、结果在什么条件下成立、在什么条件下可能失效。这些判断才是实验报告的"肉"，跑通的截图只是"皮"。通常我给同学的建议是：报告里贴代码不要超过总篇幅的三分之一，剩下的篇幅留给"为什么这么做"和"结果说明了什么"。如果贴了很长一段代码，却发现拿掉它报告依然成立，那就说明这段代码不该贴，改成一句"详细代码见附录"就够了。

2. 完整跑通一次"数据清洗实验"：从选题到结论的五环节

为了让后面的讨论不悬空，我用一个模拟数据实验来演示整个过程。实验素材是一份共享单车骑行订单表，包含骑行ID、用户ID、开始时间、结束时间、骑行时长、站点信息、用户类型等字段。数据里故意混入了一些常见脏数据：用户ID缺失、重复骑行ID、骑行时长为负、超过24小时等。实验目标很明确：清洗这份数据之后，对比工作日的骑行时长和周末是否存在明显差异。整个实验可以拆成五个环节，下面逐个展开。

2.1 先定义实验目标，再动手写代码

选任何实验之前，先写一句话：你要回答什么问题。这句话决定了后面所有步骤的取舍标准。比如这个实验的目标是"对比工作日与周末的骑行时长"，那清洗的重点就是保证"时长"这个字段可靠，其次才是用户ID等元数据。如果上来先埋头写代码，很容易变成"边写边想"，最后报告写出来像流水账，读者看完不知道你到底要干什么。

在报告的"背景与目标"部分，我习惯用一句话把目标、方法和评判标准写清楚："本实验基于某模拟骑行订单数据，通过pandas完成缺失值、重复值、异常值清洗，按开始时间构造工作日/周末标记，使用描述统计与箱线图对比两组骑行时长的分布差异。"这一句话写完，后面所有内容都是它的展开。实验报告最忌讳目标模糊，读者看了三行还不知道你在做什么，再好的代码也会被淹没。

2.2 环境准备与版本锁定

环境这块看起来不起眼，却决定实验报告能不能被别人复现。我一般会新建一个虚拟环境，并把依赖写进requirements.txt，比如：

pandas==2.0.3 numpy==1.24.3 matplotlib==3.7.2 openpyxl==3.1.2

版本号以你自己的实测为准。为什么要锁版本？因为pandas 1.x和2.x在某些API和默认行为上有差异，比如append方法在2.0里被移除了，部分字符串方法的表现也不同。你本地跑得好好的，别人用新版本一跑就报错，第一反应是怀疑你的结论，而不是怀疑版本。报告里写一句"Python 3.10.12，依赖见requirements.txt"，能省掉很多后续解释成本。

2.3 数据清洗核心环节：缺失值、重复值、异常值

下面这段是实验的核心代码，它只保留清洗过程，不涉及无关探索，方便你在报告里直接引用：

import pandas as pd df = pd.read_csv("bike_trips.csv", encoding="utf-8") print("原始数据量:", df.shape) print(df.isna().sum()) # 缺失值：没有用户ID的记录无法归属到具体用户，直接剔除 df = df.dropna(subset=["user_id"]) # 重复值：同一骑行ID出现多次，保留第一次 df = df.drop_duplicates(subset=["trip_id"]) # 异常值：骑行时长为负或超过1440分钟（24小时）视为不合理 df = df[(df["duration_min"] > 0) & (df["duration_min"] <= 1440)] # 构造"是否周末"字段：周一至周五是工作日，周六周日是周末 df["start_time"] = pd.to_datetime(df["start_time"]) df["is_weekend"] = df["start_time"].dt.weekday >= 5 print("清洗后数据量:", df.shape)

注意，这里对缺失值的处理策略是分字段的。user_id缺失没法合理填充，直接删；但如果是价格、时长这类数值缺失，可能会考虑用均值、中位数或前后值填充，具体要看业务含义。实验报告里如果能把"为什么这个字段用删除，那个字段用填充"写出来，会比贴十行代码都更能体现理解深度。我见过很多同学在报告里写"数据清洗后得到较干净的数据"，却不说清洗规则，这是很可惜的，因为清洗规则恰恰是最有信息量的部分。

清洗过程最好记录前后数据量变化，形成一条"漏斗"：原始10万条，剔除缺失用户ID 1200条，去除重复记录300条，筛除异常时长500条，最终得到9.8万条。这个数字变化放在报告里，读者一眼就能看出你的清洗动作有没有实际效果，而不是笼统的一句"清洗后更干净了"。

2.4 统计对比与可视化输出

清洗完先看数字，再做图。分组统计我用groupby：

stats = df.groupby("is_weekend")["duration_min"].agg(["count", "mean", "median", "std"]) print(stats)

接着画箱线图。这里要提一个细节：骑行时长通常是偏态分布，个别人骑很久会把均值拉高，所以不能只看均值，还要看中位数和分布形态。箱线图能把四分位数、离群点同时展示出来，很适合做分组对比：

import matplotlib.pyplot as plt plt.rcParams["font.sans-serif"] = ["SimHei"] # 让中文正常显示，Linux可按需换字体 plt.rcParams["axes.unicode_minus"] = False df.boxplot(column="duration_min", by="is_weekend") plt.title("工作日与周末骑行时长对比") plt.xlabel("是否周末（False=工作日，True=周末）") plt.ylabel("骑行时长（分钟）") plt.savefig("duration_compare.png", dpi=150, bbox_inches="tight")

保存图片时用dpi=150并加上bbox_inches="tight"，图片放到Word或PDF里不会发糊，也不会被裁掉坐标轴标签。这个细节我强调过很多次，因为实验报告里图表清晰度直接影响专业感。图片文件名用有意义的英文，比如duration_compare.png，别叫111.png或未命名.png。另外，箱线图上的离群点并不是一定要删除的异常值，恰恰相反，那些点可能就是真实存在的高强度用户，只看它们也是一种线索，在报告里可以顺带提一句。

2.5 从数字回到假设：结论该怎么写

假设清洗后的结果是：工作日样本约6.2万条，平均14.2分钟，中位数11分钟；周末样本约3.6万条，平均16.5分钟，中位数13分钟。那么结论应该怎么写？我推荐"数字+趋势+局限"的写法：

"在本数据集范围内，周末平均骑行时长约16.5分钟，比工作日的14.2分钟高约16%；中位数分别为13分钟和11分钟。但从箱线图看，两组分布重叠部分很大，个体差异明显，因此只能说存在趋势，不能据此断定工作日与周末有显著差异。若要严格验证，可进一步做独立样本t检验或bootstrap置信区间。"

这种写法好在哪？它没有把"平均差异"当成定论，而是同时给出分布重叠和样本量信息。实验报告最怕的就是下结论下得太满，一句"结果符合预期"或者"存在明显差异"就完事，后面没有任何数字支撑。好的结论一定是从数据里长出来的，而不是从假设里搬过来的。

3. 踩坑手记：五个让实验报告"翻车"的典型问题

写实验报告最磨人的不是写代码，而是排错。下面这五个问题，我几乎每次带人做实验都会碰到，每一个都有具体现象、定位过程和修复方式。把排错过程写进报告，往往是最有"含金量"的部分，因为它展示了你的真实推理能力。

3.1 中文乱码：UnicodeDecodeError的完整定位链路

现象：用pd.read_csv读一个含中文列名的csv文件，第一行就报错：

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc4 in position 0: invalid continuation byte

很多人第一反应是把encoding参数改成"utf-8"，发现没用，又改成"gbk"，可能就好了，但完全不知道为什么。我的建议是先确认文件真实编码，再看读取参数。一种快速定位方法是直接读文件字节：

with open("bike_trips.csv", "rb") as f: print(f.read(30))

如果输出的字节里能看出中文区域有类似\xc4\xe3这样的高位字节，大概率是GBK系列编码。这时可以把读取参数改成encoding="gb18030"，gb18030是GBK的超集，兼容性更好。更彻底的做法是先用工具把源文件统一转成UTF-8，后续所有环节都用UTF-8，省得每次读数据都要想编码。

写报告时我的经验是：在数据说明里写清楚"源文件为GBK编码，读取时使用encoding='gb18030'"。这一句话，能救一个在Linux环境里复现你实验的读者。别看这个细节小，很多复现失败都始于编码。

3.2 链式赋值警告：设置失败的数据到底改没改

现象：代码长这样：

df[df["user_id"].isna()]["duration_min"] = 0

运行后出现：

SettingWithCopyWarning: A value is trying to be set on a copy of a slice from a DataFrame.

这行代码的问题在于：先做了一个筛选得到副本，再在副本上赋值，原数据根本没改。警告不是吓唬人，它意味着"你以为你改了，其实没改"。定位方法很简单：print一下原df的那一列，看看缺失值还在不在。修复方式是把赋值操作合并到.loc里：

df.loc[df["user_id"].isna(), "duration_min"] = 0

我在评审报告的时候，只要看到截图里有警告，就会怀疑写报告的人没有自查过输出。所以实验报告里出现的每张运行输出，都应该是在干净环境下重新执行得到的，不该带红色警告。一个带着警告的报告，就像菜里没放盐——不是不能吃，但打分的人一定会注意到。

3.3 图表里的中文变成方块：字体问题跨机器必现

现象：程序不报错，但画出来的图里中文全是方块。这不是代码逻辑问题，是matplotlib的默认字体不支持中文。解决方法是在画图前设置：

plt.rcParams["font.sans-serif"] = ["SimHei"] plt.rcParams["axes.unicode_minus"] = False

第二行很重要，否则坐标轴上的负号会显示成方块。如果是在没有中文字体的服务器上跑，要先把字体安装到系统里，再把字体名加进列表。这个坑的杀伤力在于：你本地显示得好好的，换个环境图就花了，而且不是代码能直接解决的。报告的环境说明里如果写了"依赖系统中文字体"，可以减少很多环境纠纷。

3.4 没有固定随机种子：复现时数字对不上

现象：实验里用了随机抽样，比如df.sample(5000)，第一次跑平均数是14.2，第二次变成14.5，报告里写的数字跟读者跑出来的对不上，读者会认为你的结果是伪造的。原因很简单：抽样是随机的，每次抽中的样本不同，统计量自然不同。修复方式也简单，所有带随机性的步骤都固定种子：

df.sample(5000, random_state=42)

如果是整个脚本里的随机性都要控制，可以在文件开头设置np.random.seed(42)。报告中最好单独写一句"所有抽样步骤固定random_state=42"，这会让复现变得非常顺利。这个细节看起来小，但在实验报告里属于"专业感"的标志。我喜欢问同学一个问题：如果你不设种子，那个"14.2分钟"到底是真实差别的数值，还是只是一次随机抽样的运气？这个问题能帮人理解为什么要固定随机种子。

3.5 库版本差异：同一份代码在不同环境里行为不同

现象：代码在作者的Python 3.9上运行正常，读者用Python 3.12跑同一个脚本，却报"module has no attribute xxx"。原因多半是库大版本升级后API变了。比如pandas 1.x里的某些函数在2.x里被标记为废弃，或换了位置。

应对办法就是写requirements.txt，并注明Python版本号。报告里环境说明部分，不要只写"Python 3"，要写完整版本；依赖列出关键库和版本。如果你的实验涉及科学计算或深度学习，还要把相关运行时版本也写进去，这类依赖冲突更多。版本锁定可能看起来麻烦，但它是"可复现"的最低保障。说难听点，不锁版本就相当于把实验报告交给运气。

4. 报告内容如何组织：让读者沿着你的思路一口气读完

方法再好，表达乱了也白搭。实验报告的组织方式和写代码一样，要让人顺着一条清晰的线走到底。下面这节讲的我归纳出来的报告骨架和结果呈现原则，都是我看了很多份报告之后总结出来的。

4.1 实验报告的七块骨架：每块放什么、别放什么

我推荐一份基本骨架，总共七个部分。它不一定适用于所有实验，但足够覆盖绝大多数Python实验。见下表：

表格里的"常见错误"一列，是我看报告时最高频撞见的几类问题。你会发现它们有一个共性：都在逃避表达"判断"。比如"照抄指导书"是因为没想清楚目标；"只放运行截图"是因为没提炼数字；"写结果符合预期"是因为没做差异分析。实验报告不值钱的部分，就是把别人已经知道的东西再抄一遍；值钱的部分，永远是你自己做出的判断。

4.2 结果呈现三原则：先结论、后证据、再讨论

我读过很多实验报告，结果部分写得像"运行记录"：先贴图，再贴表格，最后写一句"从图中可以看出……"。读者得自己从图里猜结论，猜对了算你运气好。更好的做法是先给结论，再用证据支撑。举个例子：

先看一个反面写法："运行结果如下图所示。可以看出工作日和周末的骑行时长存在差异，结果符合预期。"这句话等于什么都没说。差异有多大？哪个方向？样本量多少？完全没有。再看另一个写法："清洗后的数据中，工作日样本6.2万条，平均骑行时长14.2分钟；周末样本3.6万条，平均骑行时长16.5分钟，周末高出约16%。箱线图显示两组中位数分别约为11分钟和13分钟，但分布重叠较大，趋势存在，显著性未知。"

高下立判。前者是"我跑了，它就这样了"，后者是"我做了分析，证据指向某个结论，同时我知道局限在哪"。写结果部分时，我建议你先写结论这一段，再放证据，最后写局限和下一步，这就是"先结论、后证据、再讨论"。读者第一眼看到结论，就有了上下文，再看图和表格时才知道往哪个方向理解。

4.3 附录和复现方法：让别人"照着重跑"时不骂你

实验报告的附录不是摆设，它是可复现性的最后一道防线。完整代码可以放附录，但主文里只放关键片段。代码文件名用"01_load_data.py""02_clean_data.py"这种，按执行顺序排好。每个文件头部加两行注释，说明它的输入、输出和依赖。如果实验脚本需要命令行参数，在附录里写清楚运行方式，例如：

python main.py --input data/bike_trips.csv --output result/

数据文件放在data目录下，结果放在result目录下，目录结构本身就是可读的。README或者"复现方法"一节里，写三步操作：装依赖、放数据、跑脚本。三步能跑通，读者对你的信任会大幅提升。别小看这个细节，我自己收到过不少"复现不了"的反馈反馈，最后排查下来几乎都是因为目录结构混乱、路径写死、依赖没锁版本，没有一个是算法本身有问题。

5. 实验做完还不算完：把清洗流程变成可复用的技术资产

实验报告交上去，不是结束。我建议你做两件事：把流程提炼成函数，把踩坑过程记成日志。这两件事不会多花太多时间，但长期来看，收益极佳。

5.1 把一次实验提炼成一个通用函数

以数据清洗为例，实验里的清洗步骤可以封装成一个函数：

def clean_trip_data(df: pd.DataFrame) -> pd.DataFrame: df = df.dropna(subset=["user_id"]) df = df.drop_duplicates(subset=["trip_id"]) df = df[(df["duration_min"] > 0) & (df["duration_min"] <= 1440)] return df

封装之后，下次遇到相似结构的订单数据，可以一行调用，不需要重新写一遍清洗逻辑。更重要的是，函数签名本身就是你的"方法论快照"：它告诉你，面对这类数据，需要处理的是缺失、重复、异常三类问题。实验报告写得再多，最后能在日后工作中反复利用的，往往就是这种抽象出来的函数和判断规则。如果你能在报告里写一段"本次清洗规则的适用边界"，比如"假设时长字段为正数、数值单位为分钟"，那这段内容的价值会超过很多代码。

5.2 记录实验日志：报告是给别人看的，日志是留给自己的

我自己的习惯是边做实验边写"问题日志"，格式非常简单：

这张表事后看来特别有价值。写报告时，它帮你回忆"为什么当初要这样处理"；写简历或面试时，它帮你讲出"排查链路"；下次遇到同类问题时，它直接变成速查表。很多人觉得排错过程是最没用的东西，其实恰恰相反，排错过程才是你和其他只会跑通代码的人拉开差距的地方。一份实验报告能不能打动读者，往往就看它有没有真实记录"我遇到了什么问题、怎么一点点定位到根因"。

最后再分享两个实际体会。第一个体会是：如果时间有限，实验报告优先做好两件事——结果解读和可复现性说明。这两点做扎实了，即使方法部分写得朴素，整体报告也会被高看一眼。第二个体会是：现在我做实验，都是先写"踩坑日志"，再写报告正文，因为刚踩完坑时记忆最清晰，等全部做完再回忆，很多细节就丢了。那些坑不仅是报告的素材，也是你以后遇到同类问题时的救命索引。写实验报告这件事，本质上是把一次折腾变成别人也能复用的经验，折腾得越细，写出来的东西越有价值。