不給程式碼寫文件，讓程式碼文件化

小米雲豆粥發表於2017-03-29

這是程式設計師討論了很久的一個話題：要不要給程式碼寫文件？值得給程式碼寫文件嗎？

我曾經覺得這個話題實在是讓人難以應付。也認為除去一些特殊的情況（比如編寫公用 API），程式碼文件並不是那麼必要。直到有一天，我在一份程式碼檢查報告中發現，缺少文件被作為一項缺點指出來。真是這樣的嗎？

圖0：不給程式碼寫文件，讓程式碼文件化

我曾經也給我的程式碼寫文件——至少我嘗試了。我曾深信你必須給程式碼寫文件。以後對我自己，或者對其他需要看我的程式碼的程式設計師來說，文件都會是一個好的提示。直到我發現大部分程式碼文件無法反應最近更新，我就開始思考：“如果無法保證文件反應最近更新， 那寫文件的意義到底在哪裡呢？”

這個想法持續到前幾年，直到我讀了《程式碼整潔之道》這本書。我清楚認識到，如果你將文件寫入程式碼，你就沒有必要再為程式碼寫文件了。

圖1：不給程式碼寫文件，讓程式碼文件化

我的意思是，使用有意義的變數名和函式名。如果變數名字已經表明了它們所代表的意思，函式名也清楚說明了它們所實現的功能，那麼你完全不需要去讀程式碼或者讀文件來弄明白程式碼的作用。

編寫方法的時候，即使最後你的方法只有三四行程式碼，也要儘量讓程式碼簡潔。一個方法應該製作一件事情，而且方法名要表明它的功能。

對於一個類裡面的每一個成員名，都應該達到只讀名字就知道它們所包含的資訊。這個規則對變數和輸入引數也同樣適用。

遵從這些將文件寫入程式碼的規則，你就能寫出可讀性很高的程式碼。

是的，我知道，總有一些時候你需要寫程式碼完成一個複雜的演算法，或者你從網路上找到了一些複雜的不容易看懂的程式碼，你無法從中提取簡潔有用的方法。是的，總會有例外。

你是怎麼想的呢？你是給程式碼寫文件，還是將文件寫入程式碼呢？歡迎在評論中留言。

相關文章