Posts Tagged ‘documentation’

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

June 9th, 2011

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

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

這些工程師往往可以輕鬆的通過面試,但當他們真正開始工作,卻讓人大失所望。我讀了很多關於這個問題的研究,但當我越看它,就越發現這些「殘障工程師」,就好像我的英語學生一樣。他們有 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)

©2024 MR JAMIE.
網站由 Allen Hsu 設計 | Logo 動畫由 Wen Chen 完成