🔧 阿川の電商水電行
「程式就是設計書」的重新思考契機
「沒有詳細設計。沿用現行。請參考原始碼了解規範。」
在某個現場聽到這樣的話時，我心裡隱約感到「這可能不妙」。
雖然有設計書，但內容幾乎是空白的，只有稍微寫了一些畫面形象和資料表定義。關鍵的處理流程，以及為什麼會這樣的討論幾乎沒有提及。
即使詢問設計負責人，回來的答案大致上也是這樣。
「因為是沿用現行，所以細節請參考原始碼」
當我打開期待中的既有程式碼時，那裡等著我的卻是另一種絕望。
- 完全沒有重構的痕跡
- 一個方法一大堆行數亂七八糟
- 各種「〜Manager」、「〜Helper」的名稱雜亂無章，責任界限不明確
「如果就這樣模仿下去，未來根本沒有人看得懂……」
當我這樣想的時候，我第一次真切地感到「必須讓程式碼能夠傳達設計意圖」，於是我拿起《程式設計原則》。
之前的我：依賴設計書
老實說，在那之前我的想法相當依賴他人。
- 設計是偉人的工作
- 只要符合實作者的檢查清單，並通過整合測試就行
我以這種心態進行工作。
對於「設計書和程式碼是否對應得當」幾乎沒有意識。每當在調查錯誤時，
- 花時間搜尋設計書對應的地方
- 每次都猜測設計書和程式碼哪一個是「正確的」
- 即使想寫JUnit，卻不明白規範的真正意圖
這樣艱辛的工作讓我有些無奈，卻也半心半意地放棄了。周圍的實作者大致也有相同的感受，所以越加難以產生疑問。
因為對框架的特性了解不深，所以試圖自己實現Spring已經提供的功能，反而一再重複發明輪子。
- 本來用一個設定就能解決的問題，卻努力用程式碼實現
- 不順利，反而在除錯中花了好幾個小時
我真心認為，心懷不滿地寫程式是「正常」的。
書中打動我的觀點是「哪個才是真正的設計」
讀完《程式設計原則》，最打動我的是，並不是那些細小的技巧，而是以下的思考方式。
設計書不可能完美，最終留下的「事實」只有程式碼。
直到那時，我一直認為，
- 設計書是「正確的」，而程式碼則是遵循它的產物。
但當我被扔進一個幾乎沒有詳細設計的現場時，實感卻是正好相反。
- 設計書會不被更新，很快就過時
- 設計者異動或離職後，意圖無法知曉
- 最值得信賴的，最後還是程式碼
「那麼，我寫的程式碼就是能夠長久保存的設計書了吧？」
一想到這裡，「程式碼就是設計書」這句話，不再是他人的空話，而是直接落在我自己的責任上。
首先改變的是「不再用名稱掩蓋」
既然無法立即大幅改變設計，我最先著手的就是最接近的地方。
要仔細考慮變數、方法和類別的名稱。
實施後，發現比我想像中還要困難。
- 想逃避到「〜Manager」和「〜Helper」這種模糊的名稱
- 一個方法做了太多，無法好好解釋
也就是說，
名稱決定不了 = 責任不明確的徵兆。
因此，當遇到名稱困境時，我決定這是「重新思考設計的時機」，開始進行以下的循環。
- 試著將處理過程細分
- 給每個部分貼上「我能自信地說出來的名稱」
- 若仍感困惑，則進一步細分或改變角色
雖然距離完美仍遙不可及，但我感覺自己已經走出了「依照設計書寫程式就好的消極風格」的一步。
將JavaDoc視為「第二份設計書」
我還有一個改變是對JavaDoc的使用。
之前的我，
- 只是形式上填寫
- 只是重述方法名稱的說明
在設計書薄弱的現場工作後，我開始思考，
如果設計書不可靠，那麼只能在程式碼中清楚說明意圖。
從那之後，我在撰寫JavaDoc時，開始意識到以下幾點。
- 這個方法是做什麼的
- 為什麼是這樣的規範（如果有背景或限制，即使一句話也寫上）
- 呼叫方可以期待什麼
不僅是「這樣運作」的事實，還附上「為什麼這樣做」的理由，盡可能保留。
我決定在心中將設計書不完美的前提下，
將JavaDoc視為「第二份設計書」。
儘管如此，仍然距離理想有很大差距
當然，現階段的我還未寫出理想中的程式碼。
- 雖然心裡想「應該可以更精緻」
- 但缺乏改善方法的知識和經驗
- 因為與時間表的考量，不得已妥協
這樣的情況如實存在。
不過，我至少仍然會意識到這幾點。
- 將處理細分到盡可能細
- 透過名稱和註解傳達「意圖」
即便無法做到完美設計，我的目標是讓
後來閱讀的人「知道我想做什麼」。
在這一點上，這就是我對「程式碼就是設計書」的處理方式。
給同樣感到困惑的人
儘管我並沒有什麼高大上的頭銜，只是一名普普通通的實作者，但我相信，
- 曾經在沒有詳細設計的現場迷失過的人
- 對設計書和程式碼的不一致感到些許困惑的人
「試著把程式碼當設計書來寫」這個觀點，相信是有相當效果的。
並不需要一次做出大改變，先從
- 不用名稱掩蓋
- 在JavaDoc和註解中保留至少最低限度的「意圖」
開始著手，至少能在「未來的我」閱讀時，顯著減少壓力。
原文出處：https://qiita.com/tomo19950806/items/cafe6f78776d4bc45252
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
