第二步:把 README 补全
把缺的三节补进 README,输出补之前和补之后缺几节。
第三步:把剩下两类也修掉
给三个函数补上说明、把坏示例改对,输出三项合计从多少降到多少。
交付:一份能让人照着跑通的文档
这是本条路线的最终作品。把四条检查合起来,一次验完五条: 原始文档缺 3 节、3 个函数没说明、1 个示例跑不通,合计 7 处 照 README 跑会卡在第 3 步,只走过 2 步 补齐三类问题后,三项合计降到 0 把缺的文件补进仓库后,四
在真机上验证文档,先做什么
拿到一个陌生仓库要验证它的文档,第一步是【0】。
怎么算"文档验证通过"
在真机上验证一份 README,通过的标准是【0】。
验证通过时该看到什么
一份文档验证通过时,四项检查应该是什么样?运行下面这段程序: def missing(need, have): return [s for s in need if s not in have] def no_doc(funcs)
只照 README 把项目跑起来
场景:~/proj 是一个你从没见过的项目。 任务:只读 README、不看源码,照着它把项目跑起来;程序跑通会打印 RESULT = 某个数,到 ~/对照表.txt 里查那个数对应的标记。 (判分只看你在受控容器里做出的真机产物:找东西类
找出 README 里第一处照做不通的地方
场景:~/proj2 是另一个项目,它的 README 有问题。 任务:照着 README 的编号步骤一步步做,做到哪一步失败就停下来;到 ~/对照表.txt 里查那个步号对应的标记。 (判分只看你在受控容器里做出的真机产物:找东西类到 ~
把那处问题修好并验证
场景:~/proj2 照 README 做会卡在某一步。⚠️ 先判断该修哪边:这次文档是对的,缺的是仓库里的东西——README 的「配置」小节写了它该是什么内容。 任务:把缺的东西补上,让人能只照 README 从第 1 步跑到打印 RE
给一个函数补上说明
场景:~/proj/lib.py 里有几个函数,其中一个没写说明——就是行为最不明显的那个(会抛异常)。 任务:给它补上文档字符串,写清:它做什么、参数、返回、异常(这四个词都要出现)。补好运行 ~/check(它调用 tools/docc