浅谈LP

2018-05-20 本文已影响165人俞子将

1.  [源码与文档](#1)
    1.1  [只编码，不写文档](#1.1)
    1.2  [分离的源码和文档](#1.2)
    1.3  [源码中插入文档](#1.3)
    1.4  [文档中插入源码](#1.3)
2.  [文学编程](#2)
    2.1  [文学编程的好处](#2.1)
    2.2  [常用文学编程工具](#2.2)
3.  [参考资料](#3)

LP(Literate Programming)，即文学编程。它的想法是，构造程序时，我们应该用文学的语言解释代码给人看为主要目的，而不是单单编码给计算机运行。

在开始正式介绍LP前，我们先谈谈程序员中永恒的话题，编码与文档的关系。

1. 源码与文档

程序员对这的态度或行为，大概可以概括为以下几类：

只编码，不写文档
分离的源码和文档
源码中插入文档
文档中插入源码

这里的文档泛指用来阐释源码的文字，它可能是个独立的文件，也可能是源码中的注释等等。好的文档，能帮助开发者快速地读懂源码也有利于将来的维护。

1.1 只编码，不写文档

这类程序员往往以Linus说过的 "Read The F*cking Source Code" 为宗旨（可以称为RTFSC党)。RTFSC党会认为自己写的代码清晰明了、通俗易懂、老少皆宜，完全没有必要再编写文档、注释等等。他们可能会说，我函数名起得这么好、我链式语法写得这么棒、我用promise写异步、我amb求值器设计得这么好，这样的代码你都看不懂？还要我写文档？要你何用？

虽然大多数程序员都自认为自己的源码写得巧夺天工，但是在别的程序员眼里，往往是又臭又长的存在。当一个程序员看到一段复杂的逻辑而没有一个文档说明，往往杀人的心都有了。甚至，开发者在数月后看自已以前写的代码，如果没有文档，可能自己都看懵逼了。

下面是摘自 14th国际c语言混乱大赛的代码。只要你愿意，理论上可以把任何代码写成飞机。

1.2 分离的源码和文档

这类程序员应该是比较常见的。不管主观愿不愿意，他们除了输出源码文件，还会输出对应的文档文件。要编写文档了，程序员们会创建独立的word文档，或者更有追求的可能会选择创建MarkDown、reST、AsciiDoc、DocBook、OrgMode等标记文档。

编写文档有可能在编写源码前，也有可能在编写源码后。他们可能在编写源码前，编写好相关的独立的设计文档，再按设计文档来开发代码。也可能在编写源码后，补充文档，用来日后交接工作等。

文档完成后，与源码文件往往是分开存储的，存不同的目录。在版本管理上，往往会创建不同于源码的文档工程，用来专门保存文档。

1.3 源码中插入文档

相比RTFSC，他们往往会在代码中加入大段的注释。函数、类都有规范的写注释方式。往往还有配套工具，支持从源码中抽出这些注释，再生成独立的文档。比如，doxygen、javadoc、appledoc、swagger-ui等。

这方面做到极致的是，我觉得是swagger-ui。它主要是给后台生成在线接口文档的。通过在java代码中，插入一些格式化的注释，它会生成接口的静态网页文档，并启动web服务加载。而且，你除了看在线接口文档外，你还可以在线填写参数测试接口，它会用curl进行接口请求，并显示结果，简直不要太爽。大家感兴趣可以去看看swagger-ui的demo。

有些程序员还不满足于在源码中插入普通的文本注释，还想在源码中插入流程图、交互图等。但是，源码作为纯文本文件又不能插入图片，于是只能插入ascii art文本图。如果，你给你的复杂源码中插入类似如下这么个流程图，看代码的人肯定会感动得痛哭流涕。

网上有在线生成ascii art的网站asciiflow。Emacs里也有 AsciiMode、figlet、picture等mode可以画ascii art图。

1.4 文档中插入源码

最后一种，是在文档中插入源码。它与上一种在源码中插入文档相同的是，它们的文档和源码都是放在一起的。不同的是，它强调编程应该面向人，应该以提供解释说明为主，而不是为了写出计算机可以识别的程序。

这就是文学编程的思想，即更主要目的是文学，而不是编程。

因为是主要是面向文档的，所以这里的文档可以比代码中插入的注释丰富很多。不少文学编程工具，往往提供统一显示文档和代码块的界面。比如，学习python的可能都接触过的jupyter notebook。

jupyter中可以用markdown来插入图片、链接跳转、数学公式等。同时，其中的代码块也能直接运行，并在文档中插入运行结果（如画图、表格等）。

还有其他工具环境，类似swift playgrouds、org-mode 也提供了文学编程的能力。特别是org-mode 甚至可以在一个文档里插入多种不同语言的代码块，所以在它里面，你可以用你擅长的不同语言来处理不同的事情。

2. 文学编程

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.
(Knuth 1984)

IT界大佬Knuth 认为，构造程序时，我们更多地应该从写作的角度出发，用文学的语言解释代码给人看为主要目的，而不是以编码给计算机运行为目的。

注: 还有个RR (Reproducible research)，可重复性研究，与LP有些相似的概念，可以在文末的参考资料中查看二者的区别。

文学编程，从写作、文学的角度出发，代码只是以代码块的方式插入到文档中。随后，文学编程工具一般还提供Tangle功能，可以从整个文档中抽出全部代码，也提供Weave功能，可以把文档导出成html、pdf等更通用的文档格式。

以org-mode 为例：

org-mode 是类似markdown的格式化文本。文档中可以插入图片、表格等元素，并且可以插入 #+begin_src 和 #+end_src 围起来的代码块。org-mode中的代码块可以是任何语言，在org-mode里面执行后可以把输出（图片、表格、raw）等插回文档。它也提供 Tangle 和 Weave功能，对org-mode文档进行代码提取或格式导出。

2.1 文学编程的好处

文学编程把描述和代码块放一起，并且代码块可以运行，它提供了以下好处:

科学计算等场景，随时要验证理论是否正确，如果把理论文档和代码块放一起，可以随时验证理论是否正确。
软件开发场景，丰富的文档和代码放一起，更能理解代码实现，也利于以后维护、扩展。
教学场景，往往需要一步步、手把手地写代码(hand in hand)。一个步骤一个解释配一个代码块的方式，学员更容易理解，而且可以自己动手运行代码块尝试。

2.2 常见的文学编程工具

下面介绍文学编程的一些比较流行的工具/环境：

Jupyter notebook

首先介绍 jupyter notebook。

近年来，随着机器学习 的迅猛发民，越来越多的人用jupyter notebook来做数据分析、课题研究、教学等，大有取代matlib、R之势。因为它是以文档为目的的，所以最后可以直接生成报告、演示文档等，非常酷。

Jupyter notebook 有以下几个很酷的地方:

支持超过40种编程语言，包括Python, R, Julia 和 Scala。它有各种内核如ipython、iswift等。
会起jupyter server，然后用web浏览器进行开发。所以注定，它可以很方便地进行分享。别人也可以简单地用web远程连接到你的jupyter server上，就可以开发了。
跟大部分文学编程工具一样，代码块可以产生丰富的内容，如网页、图片、视频等，再插入到文档中显示。
最后，jupyter抽代码和导出文档功能也很齐全。