代碼命名規範

該篇日誌是一篇閱讀材料的總結。文件下載地址： https://class.stanford.edu/c4x/Engineering/CS-144/asset/Naming.pdf

（也可從百度雲盤下載： http://pan.baidu.com/s/1hqf6KIw）。總結以下：

1. 名稱應該反映代碼做者的目的。
2. 1. 這節省了沒必要要的註釋（如 int t; // Time since born in days 能夠改成 int daysSinceBorn;），並使代碼變得易於讀懂。易讀和易於互相討論，這將是如下所有命名規範的關注點。關於註釋的另外一個須要注意的問題：時間緊張時，沒有多少人會讀註釋，而是由名稱猜含義。
   2. 避免出現魔術數字，用宏定義取代數字；避免’莫名其妙的操做’，各類判斷或循環控制語句讀起來應該儘可能像正常的句子。
3. 避免歧義。
4. 1. 計算機科學中有一些字母組合，由於廣爲人知全部具備了約定俗成的含義，如hp，aix，list等。因此一個「nameList」的變量，會立刻給人以「這是一個鏈表」的印象；若是它事實上不是一個鏈表，那麼「AccountGroup」就是更好的名字。
   2. 另外一種致使歧義的緣由是兩個名字長得太像。好比「ThisIsOneName」與「ThisIsOnName」區別小且不宜一眼看出。另外，小寫L（l）和1在有些編輯器裏很像，0和O也是如此；應留心這一問題。
5. 不一樣名稱的含義應該有明顯的區別。如「StellarInfo」和「StellarData」在含義上沒有什麼區別，若是用來表明兩個不一樣的東西，則很容易讓使用者（本身或他人）用錯。這能夠認爲是上面講的‘歧義’的一個變種（不是跟約定的名稱衝突，而是在語義上和本身的其餘名稱衝突）。
6. 與上面相關的，一個概念應該使用同一個單詞。好比有兩個類，Dog和Cat，那麼用’feet’和’paws’來分別表示「狗的爪」和「貓的爪」就不是好習慣，由於這樣你就不得不記清楚究竟狗和貓哪個對應feet。可是--
7. 若是一個單詞對不一樣對象有不一樣的含義，不能爲了’一致性’而使用，而是應該對特定的類型選擇最爲合適的名字。好比兩個數字相加，用’add’；向一個列表中加入元素，彷佛也能夠用’add’，但意義卻與上面的兩者’相加’明顯不一樣。故應考慮’append’。
8. 使用可以拼讀的名字。好比「tpshms」就沒辦法拼讀，這樣在跟其餘程序員討論時，就只能「tee-pee-es-aich-em-es」這樣一個字母一個字母來講，費時費力；相反的，「userId」就贊成多了。
9. 名字應易於搜索。這具備很明顯的實際意義：快速定位到感興趣的變量的定義處，對高效地理解一段代碼相當重要。不易搜索的變量名包括單獨的數字和字母個數少的字符串等。好比，5這個數字就很難grep到目標位置，但定義一個宏：MIN_ELEMENT_NUMBER就很容易搜索到。原則上名字的長度應大體和其所在的域的代碼長度成正比；但不管如何，儘可能用描述性強的名字。
10. 不要使用表示類型的前綴。匈牙利命名法在數據類型較少的時代是有用的，但現代編程語言，類型多種多樣，且能夠互相嵌套，用匈牙利命名法或相似的命名法，只會致使不少不容易發音，且本質上沒人關心的前綴。一句話：命名時只關注該變量的含義，不要管它的類型。
11. 避免無心義的命名。如循環指標使用i,j,k就是壞習慣。它們沒有任何意義。
12. 不要耍小聰明。好比使用特有的典故（#define hu_lu_wa 7）；但閱讀代碼的人可能來自不一樣的文化，徹底不懂這裏面的幽默，所以只會致使困惑。實在忍不住要寫，就把幽默放到註釋裏去，不忙的人或許會讀一讀。
13. 使用合適的動詞-名詞結構。好比一個類的method，能夠命名爲getName（這種首個單詞小寫，後面單詞首字母大寫的方式，稱爲camel casing）；名稱更改操做能夠是’fred’.changeNameTo(「mike」)，注意到裏面甚至用了介詞to--目的只有一個：讓一個函數語句像是一個正常的句子。
14. 明確兩類命名方式。一類命名反應技術細節，一類命名描述特定對象。基本精神是，位於軟件結構的最外層函數應該更反映對象自己的性質，好比car.weight()或star.age()；而底層實現應該與解決方案相關—這是很天然地，由於一般底層實現是不依賴於具體對象的，好比經常使用的庫裏的函數。
15. 對可能形成歧義的變量名添加上下文。好比一個變量名爲tree，就很難肯定它是數據結構裏的各類樹，仍是森林裏的一棵樹。解決方案是把它放到一個類/名字空間/函數裏面；或者加前綴也是個辦法，好比oak_tree。
16. 不要添加無謂的前綴。好比你要給學校寫個網關軟件，裏面的地址命名爲sjtuAddress就不是好習慣；由於全部的變量都具備sjtu這一屬性，因此乾脆都不要寫。
17. 與上面相關的一點：越具備描述性越好，並不意味着名字裏的字母越多越好；事實上，在一樣清晰地狀況下，字母越少越好。
18. 若是你發現之前代碼的名字不合理，不要由於擔憂’其餘程序員可能會抱怨’而不去採起行動。事實上，通常來講他們會感謝你把名字修改地更加合理。