论写文档的重要性

本文不是一篇技术贴，是一篇个人这一年学习的感悟。

作为入行一年的初级PHP程序员，在这一年的学习中越来越感觉，不仅仅要写出高质量的代码，还得写出好文档。

高质量的代码真的很重要，阅读高质量的代码就感觉像是在看高质量的漫画一样，从变量或方法的命名，到复杂逻辑的分解，甚至一个注释的空格，都不能多一个或少一个，记得上个月写代码注释时，//符号与注释间少了个Space键，都是不被允许的。引用Boss的一个观点：“程序员有两种，一种是只为自己写代码，而不为别人考虑；一种是为了伙伴写代码，尽量不要给别人留坑添麻烦”。完全赞同这种观点，只有精雕细琢才能写出优美的代码，高质量的代码，不给队友添麻烦。

同时，个人感觉一个好的文档也非常非常重要，会极大提高团队的效率。很多代码的逻辑都是业务逻辑，如果有一份好的文档来详细解释一些业务的东西，这对新成员是非常有帮助的，如果仅仅看代码是很难搞清楚代码逻辑。每一个Repo都有每一个Repo的业务作用，它的设计一定是根据业务逻辑来的，包括表的字段设计，数据处理的逻辑，等等这些，如果有详细的文档做支撑，对新成员快速融入非常重要。还有包括对Repo的代码逻辑，和涉及到相关知识点或工具的解释，都可以写在对应Repo里的文档，而且文档又是可以供大家Git相互协作完成。代码和文档是分不开的，也不能分开才对。

最后，推荐下Atlassian的文档管理工具Confluence，这是收费的Web App，但极大提高效率，所以软件费用算是小钱了。Confluence的功能倒是很强大，实际上Atlasssian家的软件从聊天协作工具HipChat，文档管理工具Confluence，Continues Integration工具Bamboo，项目管理工具JIRA，Git客户端管理工具SourceTree，代码托管平台Bitbucket Server，这些工具有收费免费的，都非常棒，我司也在用，用的也很顺手，值得感兴趣的关注下。当然这不是广告，只是觉得不错推荐下。好的生产工具能极大提高生产效率。

这里发表一个极端观点：如果在团队中还在用QQ等非常棒的社交工具做团队任务协作工具，要么向团队推荐HipChat或Slack这样的协作工具，要么如果建议不被理睬就赶紧走人，别在这种不重视技术的地方浪费时间了。

做一个为了伙伴去写代码的程序员，写得了好代码，也写得了好文档。

欢迎关注Laravel-China。

RightCapital招聘Laravel DevOps