论写文档的重要性

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

作为入行一年的初级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

    原文作者:lx1036
    原文地址: https://segmentfault.com/a/1190000007005069
    本文转自网络文章,转载此文章仅为分享知识,如有侵权,请联系博主进行删除。
点赞