Posted on 1条评论

请你好好写README.md

我已经记不清多少次提醒初学的人认真对待README.md,有的听,有的不听。

写代码的都假设代码是天下最重要的东西,代码比文字、声音、图像都重要。

错的。

代码比文字、声音、图像,是其中最差的沟通工具,所谓“stop talking,show me the code”只有在双方都理解架构和实现上下文的基础上才能成立,否则,如果你和别人沟通项目,尤其是在较高层次沟通有一定维度的问题,最好的媒介不是代码,而是文字、声音、图像。

所以你该认真地对待README.md,不要觉得这就是个放“非代码”的文件而没有你的.js,.html,.css,.php,.py文件重要,这样理解是错的。

一个很重要的理由是当别人从你简历来到你的github,点开项目首先看到的就是README.me的内容,如果这个文件和潦草,没人会去翻看你的代码,这时候你代码写得再好都没意义,别人的印象就是,“这孩子习惯不好,根本不认真”。

我不是要说README.md是“门面”,虽然它是,但如果只这么认为就肤浅了。README.md是项目的提纲挈领,项目的第一份文档,也可能比其他所有技术文档都容易读;README.md还是项目的营销,你可以在里面嵌入演示图片,动画,视频,外链等等,能最大限度勾起其他技术人对你代码的兴趣。

对于新repo,写README.md的过程,是“literal programming”的实践,不写代码,写“思路”,不用编程语言,用自然语言,这是Donald Knuth在多年前就提倡的开发实践。好的雕塑家在下刀之前,心里已经有了作品雏形,这是一种高超的直觉和习惯,很值得训练。编程之前先从README.md这个文档开始,把思路、疑问,可能的方案,研究方向大致写下来,在内心先“演练”一番,你会发现项目往下进行往往可以流畅很多。

请你重视README.md,它不难,但很重要。

1 thought on “请你好好写README.md

  1. 一个很重要的理由是当别人从你简历来到你的github,点开项目首先看到的就是README.me的内容,

    s/README.me/README.md/

发表评论

电子邮件地址不会被公开。 必填项已用*标注