寫程式碼就是學一門語言然後開始擼程式碼嗎？看完了我的[《GoF設計模式》](https://www.bughui.com/2017/06/10/gof-design-pattern-overview/)系列文章的同學或者本身已經就是老鳥的同學顯然不會這麼認為。程式設計是一項非常嚴謹的工作！雖然我們自嘲為碼農，但是這工作畢竟不是真正的搬磚，我們是軟體工程師。程式設計需要關注的問題太多，不僅僅有語言，還有演算法、資料結構、程式設計技巧、編碼風格、設計、架構、工程化、開發工具、團隊協作等方方面面，涉及到很多層面的問題。本文將分享一下根據我這幾年來的程式設計經驗總結出的一些關於如何寫程式碼的個人見解。 由於“跟我混”的一些小夥伴程式設計功底相對來說比較薄弱，所以在此總結一篇“程式設計內功心法”幫助他們渡過職業生涯的第一個瓶頸期。順便，也造福一下路過的有緣的同學！於是有了此文。 # 前言 首先，思考一個問題，何謂程式設計？程式設計就是寫程式碼嗎？ > 所謂的程式設計，其實就是不斷的對這個現實世界中的問題建立模型並將其固化為程式碼自動化執行的過程。 ~ [Bug輝](https://www.bughui.com) 《[GoF設計模式 - 直譯器模式](https://www.bughui.com/2017/08/14/gof-design-pattern-interpreter/#section-7)》 在對問題建立模型的過程中，我們會遇到非常多不同層面的問題，所以我們需要很多領域的知識去解決這些問題。 * 我們需要管理被操作的資料，因為資料與資料之前是相互有關聯的。將資料結構化，通常是程式設計的第一步。關於結構化資料的相關理論以及實踐，需要有一個專門的學科分支或者說課題去研究——**資料結構**。 * 我們需要解決一個具體的問題，這個具體的問題如何一步步去解決，過程是怎麼樣子的——**演算法**。 * 我們需要將解決方案進行自動化，並以程式碼的形式進行交付——**程式語言**。 * 如果將一個抽象的模型進行編碼實現，如何實現“這個功能”，如何實現“那個功能”——**程式設計技巧**。 * 問題的規模大了，眾多程式碼糅合在一起，連程式設計師自己都看不懂了！怎麼來拆分、模組化這些程式碼——**設計**。 * 程式碼量已經到了一個人無法完成的地步了，需要團隊分工合作才能完成了——**工程化**。 * 你寫的程式碼我看不懂，沒法呼叫或者很難呼叫，我寫的程式碼你也看不懂，或者很難看懂。還怎麼愉快的玩耍——**編碼風格/編碼規範**。 * 問題的規模繼續擴大，到了系統工程的規模了，之前學的套路已經不管用了！怎麼來構建這個系統才能實現正確、安全、高效能、高可用——**架構**。 然而這些也只是一個系統工程中的冰山一角！這是一個龐大的體系。也正是因為軟體開發需要考慮到的問題太多且團隊成員水品參差不齊，所以團隊開發中並不是每個程式設計師做的事情都是一樣的。每個人都有自己的角色、初級工程師、中級工程師、高階工程師、架構師、CTO。。。 所以程式設計不僅僅只是堆砌程式碼！ 說到這裡，我想起來了一件事情——為啥業界普遍鄙視培訓出來半道出家的新人？人與人的區別是很大的！我見過培訓出來也很牛的。其實，說到底，被鄙視的並不是所有人。而是那些培訓了幾個月之後發現隨便找個工作也能拿“高薪”然後還自認為程式設計很簡單的新人。因為這種經歷給了他們一種錯覺——程式設計如此簡單，我培訓幾個月也會嘛！有點像剛學會開車的新司機，很囂張的對老司機說“開車很簡單嘛！你看我也會啊！”。語言和開發工具只是招式，這是外功。而程式設計思想、經驗是內功。這些內功並不是靠短短几個月的培訓能夠掌握的，這一點有點像中國製造業和日本製造業的區別。動不動趕英超美可不好。。。 程式設計並不簡單！這是一件很嚴肅的事情。不過今天，我沒有辦法介紹完所有的方面！或者說，到今天為止，我也並沒能掌握所有領域的知識。所以今天我只是分享一些關於編碼本身的一些經驗。 另外，本文主要分享如何寫程式碼，並不是如何用Java寫程式碼。所以文章中各種語言都有可能出現。 # 編碼風格 先來一個圈內的段子。 大部分程式設計師在工作中都很討厭這四件事情： 1. 寫註釋 2. 寫文件 3. 別人不寫註釋 4. 別人不寫文件 o(∩\_∩)o 哈哈。。中槍了沒！ 這個段子其實反映出來一個問題，即大部分程式碼都需要通過大量註釋和文件來說明才能將意圖傳達給維護這些程式碼的程式設計師！然而，就像上面的段子說的那樣，寫大量的註釋和文件其實是一件很麻煩的事情。所以很多時候，由於嫌麻煩，註釋和文件就沒寫，導致維護程式碼的人相當的痛苦。這個苦同學們肯定都是體會過的！相當於給你個精密儀器要你維護還不給說明書。 其實，打破上面那個段子描述的那個怪圈的一個很有效的手段就是統一編碼風格。優秀的程式碼可以實現程式碼即註釋，程式碼本身就可以非常清晰的體現出它的意圖來，讓別人可以很容易讀懂。這就是所謂的可讀性！ ## 命名 電腦科學領域中最難的兩件事是命名和快取失效！命名並不簡單，很複雜。好的名字可以見名知意，非常容易理解。之所以說命名難是因為命名的過程同時也是概念提取的過程！對問題建立模型，需要提取概念並賦予其“術語”。這個過程其實是“萬里長征”中最難的一步。畢竟，設計也好，架構也罷，都有成熟的套路可以參考。唯獨這個過程，是需要程式設計者自己進行充分的思考的創造性工作！ 以下是總結出來的一些命名經驗： * 一個類是某物、某事、某人的抽象，是資料與行為的集合體。這恰好符合名詞的定義，因此 **類名** 是一個名詞！ * **方法名** 或者說 **函式名** 是某操作或者某過程的抽象，是一個動作。這恰好符合動詞的定義，因此函式名通常是一個動詞。 * 變數名寧可長一些說明清楚用途也不要用`a`、`b`、`c`之類的無意義的名稱，除非是迴圈計數器中用`i`、`j`、`k`等約定俗成的一些變數名。比如`pageIndex`和`pageSize`就要比取名成`i`和`s`好！取成這種和用混淆器混淆過後的程式碼一樣的名稱沒有什麼好處，如果演算法比較複雜的話，過一段時間恐怕自己都會看不懂。 * 變數名最好包含變數本身的業務含義。比如`List studentList = new ArrayList<>();`就比`List list = new ArrayList<>();`好很多。如果同一段程式碼裡再出現一個`List`的話，這樣就可以很方便的取名為`teacherList`或者`teachers`而不是`list1`和`list2`這樣的毫無意義的名稱！ ### 英文不好怎麼辦 這個問題怎麼說呢。。 作為一名程式設計師吧，基礎的英文還是要懂的。要不然發展也容易遇到天花板，學不好程式設計的。畢竟，最新的技術、解決方案、工具都是從國外傳過來的。如果是解決一些基礎性的問題，每天只做做CRUD，好像英文確實不怎麼用得上。但是一旦遇到一些實質性問題，恐怕只能到英文網站上找嘍！ㄟ(▔ ,▔)ㄏ 不要跟我說你程式設計可以不需要[Stack Overflow](https://stackoverflow.com)。**copying and pasting from stackoverflow** 可是終極程式設計大法！o(∩\_∩)o 這句話可是程式設計的真諦啊！(如果你看不懂這個梗那你有可能是偽程式設計師) 其實，話說回來，實在不方便用英文的時候，我認為也可以用拼音命名。這個問題上可以務實一點，量力而行。但是，拼音和英語混用的做法就不太好了。最好別這樣！逼格不高。 ## 註釋 ### 怎麼新增程式碼註釋 關於註釋，我們需要解決的第一個問題是如何新增程式碼註釋。 對於Java、C#之類的語言，有專用的文件註釋語法，很好處理。對於C/C++，則按約定的格式說明一下類和函式、程式碼片段的作用和意圖即可，至少編譯器會進行靜態檢查。在[**Python**](https://www.bughui.com/2017/04/17/python-grammar-notes-1/)中，有更牛逼的文件字串這樣的語言級特性支援，看註釋用`help()`很方便。不過對於[**Lua**](https://www.bughui.com/2017/04/01/lua-grammar-points/)這樣的弱型別解釋型語言，註釋就比較難處理了。這裡以Lua為例給出一種註釋的解決方案。 借用Java語言文件註釋的風格。 檔案註釋，或者說類/模組註釋。 ```lua --[[ Object-oriented helper functions for Lua @author: Elvin Zeng @date: 2017-8-21 --]] ``` 函式註釋 ```lua --[[ create a class with specified super class. if number of parameters is zero, derived class will extends from {}. @param superClass super class of target class @return derived class --]] local function createClass(superClass) local derivedClass = {} -- 省略一堆程式碼 return derivedClass end ``` ```lua --[[ register a new account @param user { username = "username", password = "password" } @return registered user --]] local function register(user) end ``` tips: [**Lua**](https://www.bughui.com/2017/04/01/lua-grammar-points/)中可以通過**metatable**機制實現類和繼承，這一點與Javascript通過原型機制來實現類和繼承有點類似。 ### 註釋裡該寫些什麼 我們首先來看個反例。 ```java /** * 查詢 */ public List

queryPage(int pageSize, int pageIndex) throws PageIndexOutOfBoundsException { // 定義一個整型變數 int offset; // 省略一堆程式碼 } ``` 首先這個方法名本身就取得不好，這個暫且不說，先說註釋問題。這裡的註釋犯了幾個錯： 1. 方法註釋為“查詢”，這簡直就是廢話！方法名已經告訴別人這是查詢方法了，還在這個註釋裡寫這兩個字有什麼意義呢？而且到底查詢些什麼這裡也沒說！ 2. 引數沒有註釋。沒有描述每一個引數的意義以及取值範圍等！ 3. 什麼情況下會丟擲`PageIndexOutOfBoundsException`沒有描述清楚。 4. “定義一個整型變數”這種垃圾註釋就不要寫了，這麼簡單的語句誰看不懂啊！如果要註釋，也是寫上這個變數的含義。 這裡我們先不考慮設計問題（分頁索引號最好做成可以自己調整成合理值），下面再來看改善註釋之後的程式碼。 ```java /** * 列出指定分頁的文章 * @param pageSize 分頁大小。如果等於0則表示查詢出所有文章。 * @param pageIndex 分頁索引號。必須為一個大於0的整數，第一頁索引為1。 * @return 指定分頁的文章列表 * @throws PageIndexOutOfBoundsException 當分頁索引號超出正常範圍時丟擲，即pageIndex小於0或大於最大頁索引時。 */ public List

listArticle(int pageSize, int pageIndex) throws PageIndexOutOfBoundsException{ // 第一條文章記錄在MySql資料庫中的偏移量 int offset; // 省略一堆程式碼 } ``` 改完之後的註釋有沒有感覺資訊更全很多！雖然說程式碼本身就是最好的註釋，但是必要的註釋還是得寫上去，畢竟呼叫的時候別人沒法猜測你的索引號到底從0還是從1開始。另外，如果函式內演算法比較複雜，可以在程式碼塊內註釋，也可以在函式註釋上直接寫清楚這個函式內部的大概演算法/邏輯。程式碼寫出來就是給別人呼叫的，如果沒有基本的註釋資訊，那麼每次呼叫你的程式碼的時候，都得去看一下你的函式內具體邏輯才能知道怎麼呼叫。這顯然是非常低效的！ 命名與註釋這兩個基本方面沒做好的話，會影響到整個團隊的運作。也就是說，你封裝的東西並沒有給隊友節省什麼時間，別人用到你的程式碼的時候，又需要花上一些時間去讀你的程式碼。如果團隊裡每個人都這樣，那整個團隊都會極其低效。我個人是非常不願意與這種程式碼風格惡劣的人合作的。 ## 參考規範 關於編碼風格的問題，本文只說命名和註釋這兩個方面。關於縮排、空格、斷行、空行等其他方面的問題，可以參考本節給出的參考規範。 不同的企業會有不同的編碼規範，所以這裡沒有辦法給出一個符合所有公司的規範。不過制定自己團隊的規範的時候，可以參考一些大企業的做法。以下是世界上最大的網際網路公司谷歌的編碼規範，同學們可以參考這個。 * [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html) * [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) * [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) * [Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html) * [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) # 異常處理 ## 異常與返回值有什麼不同 在C語言中，我們的函式通常會返回一個整型值作為狀態碼用於通知客戶端呼叫的結果。比如0表示成功，非0表示失敗。並且可以通過不同的數值來表示不同原因導致的失敗。然而在Java、C#、C++一類面嚮物件語言中，一般不會用返回值來表示狀態。返回值一般用於表示返回的業務值，而異常用於通知客戶端程式執行狀態改變了。 ## 什麼時候需要丟擲異常 關於這個問題，我想到了一句極其精煉的話：當函式**無法完成**其**宣稱的任務**的時候丟擲異常！ 比如上面的那個日子，當`listArticle`方法由於種種原因無法查詢出文章列表的時候，則丟擲異常。 丟擲異常在這種場景下是非常有必要的，因為這樣其他人呼叫你的程式碼時可以非常放心的去呼叫，只要呼叫了你的方法，就會返回文章列表。如果無法返回文章列表，則會丟擲異常。完全不用在呼叫這個函式的時候去懷疑是否執行成功了。 再來一句至理名言： >寧願終止程式也不要帶錯執行下去。 也就是說，遇到錯誤的時候，寧願丟擲異常終止程式，也不要帶著錯執行下去。這是在掩耳盜鈴！ ## 異常需要攜帶什麼資訊 首先，異常的型別本身會帶有異常種類資訊。其次，異常的`message`屬性可以帶上更詳細一些的資訊。這裡需要注意，千萬不要像下面這麼做。 ```java throw new PageIndexOutOfBoundsException("失敗！"); ``` 丟擲異常了肯定是執行失敗了呀！帶上這種資訊有什麼用，不是帶了一句廢話嘛！ 應該是下面這樣 ```java throw new PageIndexOutOfBoundsException("引數分頁索引號pageIndex不能大於分頁總數"); ``` 此外，異常堆疊也會攜帶很多資訊。 # 日誌 談到日誌，首先要搞清楚一個問題，日誌是幹嘛用的？ 用來記錄執行時的錯誤資訊啊！ 是啊。好像大家都知道日誌是幹什麼用的，但是為什麼寫起程式碼來就會忘記初衷呢！ 來看看程式碼： ```java /** * 非同步傳送通知郵件。 * @param templateFile 郵件模板檔案路徑，相對於classpath。 * @param modelMap 模型物件 */ public void sendEmail(String templateFile, Map modelMap){ // 這裡省略一些程式碼 System.out.println("1"); // 這裡省略一些程式碼 System.out.println("2"); // 這裡省略一些程式碼 } ``` 這裡的程式碼是什麼意思呢？程式設計師們應該都能明白的！很顯然，這位程式設計師是想借助這些標記來除錯，想知道程式碼到底執行到哪一行了。但是，這裡很明顯地犯了兩個錯。 1. 為什麼是`System.out.println("");`而不是`logger.debug("");`? 2. 為什麼是`1`、`2`而不是一些更明確的文字資訊呢？ 在這裡，合理的方式是下面這樣。 ```java /** * 非同步傳送通知郵件。 * @param templateFile 郵件模板檔案路徑，相對於classpath。 * @param modelMap 模型物件 * @throws ServiceException 當郵件模板檔案不存在或者modelMap中缺少必須的欄位。 */ public void sendEmail(String templateFile, Map modelMap) throws ServiceException{ // 這裡省略一些程式碼 if (isTemplateExists){ logger.debug("模板檔案存在"); // 這裡省略一些程式碼 logger.debug("郵件傳送任務成功入隊。任務id：" + taskId); // 這裡省略一些程式碼 }else{ logger.error("指定的模板檔案[" + templateFile + "]不存在，郵件傳送失敗。"); // 丟擲異常 } } ``` 我想給正在犯上面的錯的同學提個醒： 1. 使用日誌框架，並用合適的級別輸出日誌非常重要。 好多程式設計師從來不負責也不參與運維相關的工作，甚至是做了好幾年的Web都從來沒有自己釋出過網站。所以壓根沒有後期維護的意識！ 如果沒有這些日誌，當專案上線之後，運維的背鍋俠兄弟發現網站掛了之後只能直接重啟，然後當作什麼也沒看到。因為沒有排錯的線索。 2. 輸出有效資訊。 不要去輸出一些像`1`、`2`、`3`、`成功`、`失敗`、`hello`這樣的毫無意義的日誌，要輸出`logger.debug("郵件傳送任務成功入隊。任務id：" + taskId);`這樣的有效資訊。 也許當時你除錯的時候，在你看來這些奇怪的字串是有意義的，但是在其他人看來，這些就是天書。運維的背鍋俠會提刀過來砍你的！另外像`"-------開始執行--------"`這種對執行期間定位問題沒有半點好處的日誌就不要輸出了！自己用可以，提交程式碼前一定要刪掉。 3. 日誌中帶上上下文資訊。 孤立的一句錯誤日誌通常沒有什麼實際作用。比如上面的例子中，如果在找不到指定的模板檔案的時候未將傳送郵件時指定的模板檔名輸出，那麼排錯的時候無法知道到底是少了哪個模板檔案。 4. 不要在日誌中輸出使用者的敏感資訊。 千萬不要在日誌中輸出像使用者密碼、郵件內容之類的涉及使用者隱私的敏感資訊，也不要去輸出像驗證碼的值之類的敏感資訊。 # 引數校驗 在你對外公開的方法前先插入一些檢查引數的程式碼，以確保方法被“正確的姿勢”呼叫。比如： ```java /** * 列出指定分頁的文章 * @param pageSize 分頁大小。如果等於0則表示查詢出所有文章。 * @param pageIndex 分頁索引號。必須為一個大於0的整數，第一頁索引為1。 * @return 指定分頁的文章列表 * @throws PageIndexOutOfBoundsException 當分頁索引號超出正常範圍時丟擲，即pageIndex小於0或大於最大頁索引時。 */ public List