编程作品的说明文档：评委想看到哪些内容

编程作品和实物作品不同：评委看不到它“长什么样”，在有限的时间里也不可能逐行读完代码。一份清楚的说明文档，是让评委理解作品的关键。很多学生代码写得不错，却因为说明不清楚而吃亏。

说明文档的基本结构

程序结构：用图说明

用一张结构图说明程序的组成，比大段文字清楚得多。例如一个学习单词的小程序：

1. 数据部分：单词表的读取和保存。
2. 练习部分：随机出题、判断对错。
3. 统计部分：记录错误次数，安排复习。
4. 界面部分：显示题目和结果。

画出这四个部分，用箭头表示数据怎样在它们之间流动。评委看图就能理解程序的整体设计。

关键算法：讲清楚“怎么做”

每个作品都有一两个核心的处理方法，要重点说明。比如单词程序中“怎样安排复习”：答错的单词在下一轮中出现的概率提高，连续答对三次的单词暂时不再出现。可以配一个流程图，或者用一个具体例子演示。

不需要贴大段代码，用文字和图把思路讲清楚即可。

代码注释

说明文档讲整体，代码注释讲细节。好的注释应该：

• 每个文件开头说明这个文件做什么。
• 每个函数说明它的作用、输入和输出。
• 复杂的地方说明为什么这样写。

注释不需要每行都写，“为什么”比“做了什么”更重要。

测试情况

编程作品同样需要测试：

测试特殊情况的结果，往往最能体现程序是否考虑周全。

已知问题

如实写出作品目前的不足，例如“暂不支持导入图片”“在某些手机上界面显示不全”，并说明打算怎样改进。评委会认可这种对作品有清楚认识的态度。

文档写给谁看

写说明文档时，假设读者是一位懂编程、但第一次看到这个作品的人。请一位同学按照文档安装和运行作品，看他能否顺利完成、能否看懂设计思路。根据他的反馈修改文档，直到别人能独立理解为止。