Posts Tagged ‘documentation’

最棒的程式碼，不是程式碼

June 9th, 2011

上次聊過工程師的生產力不應該用程式碼來衡量，因為他們的極致生產力，是在少寫幾行程式，而不是在多寫幾行程式。今天剛好又看到兩篇文章，可以用不同的面向延伸、解釋這件事情。

首先，是一位跑去日本教英文老師的前任軟體工程師，發現了寫程式和學語言間的共通性，他說：

這些工程師往往可以輕鬆的通過面試，但當他們真正開始工作，卻讓人大失所望。我讀了很多關於這個問題的研究，但當我越看它，就越發現這些「殘障工程師」，就好像我的英語學生一樣。他們有 5,000 字的詞彙，書裡面的每一個文法都背得滾瓜爛熟，但是就是說不出一句話。

我的理論是，程式其實就跟寫作沒什麼兩樣。多數的程式概念上一點都不難 (跟你想的不一樣)，我們搞不好的原因往往只是寫作能力太差。大部分的工程師根本就不是「流暢」的語言使用者，也沒有努力想要讓自己變得流暢。他們不去多讀讀他人的程式，看不懂也不會使用「成語」，更不會「用程式語言來思考」。這些人寫出來的程式很糟，因為他們根本就是電腦語言的三歲小孩，卻試著要寫一本小說。

所以如果你是工程師，多讀讀別人的程式碼，是很重要的，就跟學習寫作一樣。

相反的，如果你的程式想要讓人家讀懂，那 documentation 是非常重要的。GitHub 工程師 Zach Holman 發表了一篇非常棒的文章，詳細解釋了為什麼你要寫文件，怎麼寫。

Documentation 是個人的 — 相信我，你以後一定會回來改這些程式，如果要讓未來的自己更快進入狀況，把事情搞定，今天請你務必把東西寫清楚。
Documentation 是清楚的 — 如果你不把你推出去的程式碼講清楚，那根本是在幫自己找麻煩，以後一定會出現一堆 bugs、困惑的同事，最後搞得自己更累而已。
Documentation 是可以測試的 — 因為你必須要把程式的邏輯解釋清楚，這讓你重新思考自己的寫出來的東西是不是符合原始精神，有沒有更好的方式。為了不在寫文件時陷入無法解釋的難關，這也迫使你簡化每一個功能，把一個複雜的東西切成好幾個功能。
Documentation 是可以比較版本的 — 好的文件可以讓版本間的比較更容易，也讓團隊合作更有效率。
Documentation 是行銷 — 透過好的文件，可以讓下載你軟體的人更容易開始使用，這也大大提升了轉換率。
Documentation 讓你在床上表現更棒 — 這點 Zach 還在驗證，不過他認為建立好的文件讓你很酷，這應該對自信會有幫助。