Srouce Code是最好的文件

軟體開發過程當中，需要不少文件作為溝通的媒介，例如需求書、系統分析書、系統設計書。在撰寫這些文件，除了文件的內容本身之外，還有其他兩種用途。第一是企業開發流程的產出。所謂凡走過必留下痕跡，做了什麼事，需要讓上級、後人知道你作了什麼事。基本上我不太喜歡用這種理由來撰寫文件，但不可否認，很多時候這是無法避免的。這種特點，在proposal中特別顯著。你會在proposal中看到明明是描述相同的東西，卻分散在不同的章節；或是明明可以用較少的字數來表現相同意思，卻一定要使用一堆文字來佔篇幅。

第二種用途是做為規格書。以專案來說，規格書代表了範疇、成本、與時間；這在專案中是極為重要的。沒有規格書的限定，專案很容易無限上岡的的擴張，而且也會讓後續的實作動作不知所措。僅管有規格書在限制需求變動，但需求變動始終是無可必免的議題。不管需求再怎麼變更，最後系統跑的一定是程式。而程式說明則是最靠近執行程式的文件。如果連這裡都沒做好適當的把關，日積月累下來，系統一定會變得非常難以維護。

一般來說程式說明有2種。一種方式，就是直接在程式碼中撰寫註解：

String b=a.getCN();//取得使用者輸入的公司名稱
String c=cstr(b);//清除空格
dao.s(c);//存入資料庫

//清除str的空格
cstr(String str){
  return str.trim();
}

如果可以，請不要這樣寫程式碼。我非常建議使用另一種方式來註解程式。就是程式naming方式。例如像這樣利用naming的方式，就可以知道這段程式是在作什麼事。

String compName =userInput.getCompName();
String savedCompName =Trim(compName);
dao.save(savedCompName);

Trim(String str){
  return str.trim();
}

一般來說，我們都會取兩種方式的優點一起使用。這樣我相信接你程式碼的人會更開心。 有時候，甚至可以使用convertCompName來說明輸入這裡有一段特殊的邏輯，需要處理，例如將小寫轉大寫之類的…。

String compName =userInput.getCompName();
String savedCompName =ConvertCompName(compName);//將小寫轉大寫
dao.save(savedCompName);

ConvertCompName(String compName){
  ...
}

Source code之所以會稱作最好的文件，一個原因除了是他是最靠近系統執行的文件外，另一個原因，他是由實作的人員所撰寫。不管軟體開發流程前頭描述得再怎麼天花亂墜、講了多少「要做什麼」，最後總是要有人鎖螺絲、敲釘子，有人要撰寫程式碼，不然一切都是空談。Source code是屬於「要怎麼作」的部份。程式碼註解，就是在說明，程式撰寫人員、或是當初開發的人員是怎麼做的。

第三個，也是我認為最重的一個原因。隨著時間的變動，系統難免有需求變動。通常來說，這時文件可能因為種種都因素，而變得年久失修，與執行程式開始不一致。而不管是什麼需求異動，到最後總會異動程式碼，那程式碼註解將是最容易修改的地方。

中國有一句俗話說得好：「取個好名字，勝過辛苦一輩子」。程式碼變數、method名字取得好，可以很輕易的說明系統資訊與程式流程。身為一個軟體開發人員，真的要隨時假設接你系統的人是一個知道你家住址、殺人不眨眼的殺手，修改的時候，千萬不要讓他起有想要殺你的念頭。系統開發的過程當中，開發人員千萬記得在程式碼中加上適當的注解。而且很可能，最後這個系統維護的人還是自己，到時候還真是得不嘗失。