Cal Evans

大學程式設計課的教訓#

在作者大學的第一堂程式設計課上，老師發了兩張 BASIC 程式碼紙。黑板上的作業是：「寫一個程式來輸入並平均 10 個保齡球分數」。老師離開了教室。

這能有多難？作者不記得最終的解法了，但確定它有一個 FOR/NEXT 迴圈，總共不超過 15 行。程式碼紙——是的，那個年代是先手寫再輸入電腦的——每張可以寫約 70 行程式碼。作者很困惑為什麼老師會給兩張紙。

由於字跡一向很潦草，作者把第二張紙用來重新謄寫程式碼，希望能因為排版整潔而拿到額外的分數。

結果令他大吃一驚——作業拿回來時只得了勉強及格的成績。在整齊抄寫的程式碼頂端，潦草地寫著：「No comments?（沒有註解？）」

註解不是邪惡的#

註解不是邪惡的。它們和基本的分支或迴圈結構一樣，是程式設計的必要組成部分。

大多數現代語言都有類似 javadoc 的工具，可以解析格式正確的註解來自動建構 API 文件。這是一個很好的起點，但遠遠不夠。

好的註解實踐#

程式碼內部應該有解釋程式碼應該做什麼的說明。遵循那句老格言：「如果它難以編寫，它就應該難以閱讀」，這樣做是對你的客戶、你的同事和你未來的自己的虧欠。

另一方面，也不要在註解上做得太過頭。確保你的註解釐清程式碼而不是遮蔽它：

• 用相關的註解點綴你的程式碼，解釋程式碼打算完成什麼
• **標頭註解（header comments）**應該給予任何程式設計師足夠的資訊來使用你的程式碼，而不需要閱讀程式碼本身
• **行內註解（inline comments）**應該幫助下一個開發者修復或擴展程式碼

一個慘痛的教訓#

在一份工作中，作者不認同上面的人做的一個設計決策。覺得自己很聰明（就像年輕程式設計師常做的那樣），他把那封指示他使用該設計的電子郵件內容貼進了檔案的標頭註解區塊。結果那家公司的管理層在程式碼提交時真的會審查程式碼。這是作者第一次認識到**「職涯限制型舉動」（career-limiting move）**這個詞。

老師和作者都知道程式應該做什麼。但作業的重點之一是教導他：程式碼應該向下一個接手的程式設計師解釋自己。這是一個他永遠不會忘記的教訓。