十大至简规则，用Jupyter Notebook写代码应该这样来

Jupyter Notebook 是一个非常常用的代码编辑器，它非常适合做数据分析与代码展示，很多云服务也采用它作为代码编辑器。此外，因为用这种编辑器看代码比较轻松，文档描述和输出效果也能进一步帮助理解，很多研究者都会采用 Jupyter 作为解释研究实现的工具。

如果 Jupyter Notebook 写的好，那么研究实现及复现就更优美，如果再放到 Colab 等具有免费算力的工具上，那就比较完美了。

在机器之心之前介绍过的文章中，我们关注 Jupyter Notebook 的炫酷插件与主题风格，更强调工具本身的使用姿态。而一篇发在 arXiv 上的文章介绍了什么是展示实现代码的十大简单规则，我该又该如何利用它们构建 Jupyter 项目。这对于研究者和希望展示项目实现的开发者而言非常重要，我们可以像说故事一样介绍我们的实现。

论文链接：https://arxiv.org/pdf/1810.08055.pdf

下面，我们就以展示可复现性研究成果为目标，看看 Jupyter 要怎样写才比较合理。

Jupyter Notebook 与研究的可复现性

可复现性(Reproducibility)需要提供研究所用数据、软件、依赖项和计算环境(如硬件或云配置)的人类可读和机器可读的描述，以及介绍如何组合以上所有部分的文档。

之前分析人员通常将这些信息保存在单独的数据、分析、结果、配置和注释文件中(这些文件通常很难组合和共享)，不过他们越来越多地使用计算型 notebook(如 Jupyter Notebooks 和 R Notebooks)，在单个交互式和可移植文档中组合可执行代码、渲染可视化效果和描述性文本。

Jupyter Notebooks 大大降低了可复现性的困难，它使科学家能够轻松地编写混合了代码、结果和文本的共享计算叙述，从而支持可复现性研究。然而，像 Jupyter Notebook 这样的计算型 notebook 并没有解决实现可复现性的所有障碍，而且它们还引入了另一些独特的挑战，其中部分挑战源于它们的交互性。

考虑到在 Jupyter Notebooks 上发布可复现研究的技术和社会障碍，来自加州大学圣地亚哥分校和伯克利分校的研究者编制了一套规则、提示、工具和示例 notebook。这套规则专注于 Jupyter Notebooks，不过也适用于其他混合了实时代码和叙述性描述的文档。

下图 1 展示了在 notebook 开发周期不同阶段所应用的规则。

图 1：将十个简单规则应用于创建 Jupyter Notebooks 的工作流。从上到下，该图描述了开发一个记录详尽、功能良好、用于可复现性研究的 Jupyter Notebooks 所需的三个不同的阶段。

规则 1：为观众讲故事

使用 Jupyter Notebooks 的一个主要好处是，它能将解释性文本与代码和结果交织在一起，创建计算性叙述 [8]。不要只保留零星的笔记，而是用解释性文字讲述一个引人入胜的故事，故事的开头介绍主题，中间介绍步骤，结尾解释结果。不仅要描述你做了什么，还要描述为什么要这样做、这些步骤是如何连接的，以及它们意味着什么。

如何讲述这个故事将取决于你的观众。你打算和实验室的非技术同事、另一个实验室的分析师、某一期刊的读者还是公众分享你的 notebook?你可能需要为每一类观众提供不同种类和级别的解释。

规则 2：记录过程，而不仅仅是结果

计算型 notebook 的交互特性使得尝试和对比不同方法或参数更加快速和容易，以至于我们在执行这些交互式调研时往往无法将其记录下来。因此，这个建议变得更加重要：确保记录下所有的探索，甚至那些导致进入死胡同的探索!这些将帮助你记住做了什么和为什么做。

许多 notebook 用户等到分析结束、得到了可靠结果后，才添加这样的解释性文字。不要等，到那时你可能已经忘记了为什么选择某个特定参数值、从哪里复制了一段代码，或者中间结果的有趣之处是什么。如果你没有时间全面记录你此刻正在做什么或在想什么，那么留下简短的描述性笔记来提醒自己，在可以停下时抓紧把这些内容添加上。

规则 3：添加分割，使步骤更清晰

notebook 是一个交互式的环境，所以它很容易编写和运行单行单元格。这有利于实验，但会让 notebook 凌乱不堪，充满难以理解的短小片段。那么，尝试让 notebook 中的每个单元格执行一个有意义的分析步骤，并且该步骤可以根据单元格中的代码或周围的 markdown 描述很容易地理解。