論寫文檔的重要性

本文不是一篇技術貼，是一篇我的這一年學習的感悟。

做爲入行一年的初級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