程式碼即文件

敏捷方法的共同元素之一，是將程式設計提升到軟體開發的核心角色，其重要性遠高於軟體工程社群通常所做的。其中一部分是將程式碼歸類為軟體系統的主要文件，如果不是主要文件的話。

我幾乎立刻感到有必要駁斥一個常見的誤解。這樣的原則並非表示程式碼是唯一的文件。雖然我經常聽人對極端程式設計這麼說，但我從未聽過極端程式設計運動的領導人這麼說。通常需要進一步的文件來補充程式碼。

程式碼之所以成為主要文件來源的理由，是因為它是唯一足夠詳細且精確的文件，可以扮演這個角色，這一點在 Jack Reeves 的著名文章〈"What is Software Design?"〉中表達得很清楚。

這個原則帶來一個重要的後果，那就是程式設計師必須努力確保程式碼清晰易讀。說程式碼是文件，並不是說特定的程式碼庫就是好的文件。與任何文件一樣，程式碼可以很清晰，也可以是亂碼。程式碼並非天生就比其他形式的文件更清晰。（其他形式的文件也可能含糊不清，我見過很多亂碼的 UML 圖，這只是眾多例子之一。）

當然，大多數程式碼庫似乎都不是很好的文件。但就像斷言程式碼是文件就排除了其他形式的文件是一種謬誤，說程式碼通常是糟糕的文件就表示它必然很糟糕也是一種謬誤。寫出清晰的程式碼是可能的，我確信大多數程式碼庫都可以變得更清晰。

我認為程式碼經常如此難讀的部分原因，是因為人們沒有認真地將它視為文件。如果沒有讓程式碼清晰的意願，那麼它不太可能自動變得清晰。因此，讓程式碼清晰的第一步是接受程式碼就是文件，然後努力讓它清晰。我想這取決於大多數程式設計師在開始程式設計時所受的教導。我的老師沒有特別強調讓程式碼清晰，他們似乎不重視它，當然也沒有談論如何做到這一點。我們整個產業需要更重視程式碼清晰度的價值。

下一步是學習如何進行，在此讓我提供一本暢銷技術書籍作者的建議 - 沒有什麼比審查更重要的了。我從未想過在沒有許多人閱讀並提供回饋的情況下出版一本書。同樣地，沒有什麼比從他人那裡獲得回饋，了解什麼容易或不容易理解，更能讓程式碼更清晰。因此，請把握每個機會，找到方法讓其他人閱讀您的程式碼。找出他們認為容易理解的部分，以及哪些部分讓他們感到困惑。（是的，結對程式設計是一個很好的方法。）

對於更具體的建議 - 我建議閱讀有關程式設計風格的書籍。程式碼大全 是第一個要找的地方。我自然會建議重構 - 畢竟，重構的很大一部分是讓程式碼更清晰。在重構之後，重構到模式 是個顯而易見的建議。

您總會發現人們在各種觀點上意見分歧。請記住，程式碼庫主要由團隊擁有（即使您對其部分內容實施個人程式碼所有權）。專業程式設計師已做好準備，可以調整其個人風格以反映團隊的需求。因此，即使您喜歡三元運算子，如果您的團隊不覺得它們容易理解，也不要使用它們。您可以在個人專案中使用自己的風格進行程式設計，但您在團隊中所做的任何事情都應遵循該團隊的需求。

於 2015 年 3 月 25 日重新發布