最棒的程序代码，不是程序代码

　　文/Mr. Jamie

　　上次聊过工程师的生产力不应该用程序代码来衡量，因为他们的极致生产力，是在少写几行程序，而不是在多写几行程序。今天刚好又看到两篇文章，可以用不同的面向延伸、解释这建事情。

　　首先，是一位跑去日本教英文的前任软件工程师，发现了写程序和学语言间的共通性，他说：

这些工程师往往可以轻松的通过面试，但当他们真正开始工作，却让人大失所望。我读了很多关于这个问题的研究，但当我越看它，就越发现这些「残障工程师」，就好像我的英语学生一样。他们有 5,000 字的词汇，书里面的每一个文法都背得滚瓜烂熟，但是就是说不出一句话。

我的理论是，程序其实就跟写作没什么两样。多数的程序概念上一点都不难(跟你想的不一样)，我们搞不好的原因往往只是写作能力太差。大部分的工程师根本就不是「流畅」的语言使用者，也没有努力想要让自己变得流畅。他们不去多读读他人的程序，看不懂也不会使用「成语」，更不会「用程序语言来思考」。这些人写出来的程序很糟，因为他们根本就是计算机语言的三岁小孩，却试着要写一本小说。

　　所以如果你是软件工程师，多读读别人的程序代码，是很重要的，就跟学习写作一样。

　　相反的，如果你的程序想要让人家读懂，那 documentation 是非常重要的。GitHub 工程师 Zach Holman 发表了一篇非常棒的文章，详细解释了为什么你要写文档，怎么写。

1. Documentation 是个人的 —— 相信我，你以后一定会回来改这些程序，如果要让未来的自己更快进入状况，把事情搞定，今天请你务必把东西写清楚。
2. Documentation 是清楚的 —— 如果你不把你推出去的程序代码讲清楚，那根本是在帮自己找麻烦，以后一定会出现一堆 bugs、困惑的同事，最后搞得自己更累而已。
3. Documentation 是可以测试的 —— 因为你必须要把程序的逻辑解释清楚，这让你重新思考自己的写出来的东西是不是符合原始精神，有没有更好的方式。为了不在写文件时陷入无法解释的难关，这也迫使你简化每一个功能，把一个复杂的东西切成好几个功能。
4. Documentation 是可以比较版本的 —— 好的文件可以让版本间的比较更容易，也让团队合作更有效率。
5. Documentation 是营销 —— 透过好的文件，可以让下载你软件的人更容易开始使用，这也大大提升了转换率。
6. Documentation 让你表现更棒 —— 这点 Zach 还在验证，不过他认为建立好的文件让你很酷，这应该对自信会有帮助。

　　以上，希望这些观念可以帮助你们更了解工程师、效率和生产力之间的关系，加油！

　　(Image via zooboing, CC license)