請快速說出以下代碼的功能：

for i in range(n): 
    for j in range(m): 
        for k in range(l):  
            temp_value = X[i][j][k] *12.5 
            new_array[i][j][k] = temp_value+ 15 

很難，對吧?要想對這段代碼進行修改或調試，除非知道作者在想什么，否則將難以實現。即使是作者本人，在編寫這段代碼幾天后也會忘記其用途，因為變量名和“魔數”(magic numbers)并不能幫助記憶代碼的功能。

使用數據科學代碼時，類似于上面(或者更糟)的示例很常見:代碼中含有如x、y、xs、x1、x2、tp、tn、clf、reg、xi、yi、ii這樣的變量名和許多未命名的常量值。坦率地說，數據科學家(包括本人)并不擅長于命名變量。

很多人經歷過從為一次性分析編寫研究導向的數據科學代碼到編寫生產水平代碼的過程，所以不得不摒棄從數據科學書籍、課程和實驗室中獲得的實踐來改進編程方式。可實際應用的機器學習代碼與數據科學家的編程方法有許多不同之處，但本文將從兩個影響力較大的常見問題開始：

• 無用的/混淆的/不明確的變量名
• 未命名的“魔幻”常數

這兩個問題都導致了數據科學研究(或Kaggle項目)和生產機器學習系統之間的脫節。是的，你可以在只運行一次代碼的Jupyter Notebook中僥幸逃脫這些問題，但是當任務中關鍵的機器學習管道需要每天準確無誤地運行數百次時，編寫可讀以及可理解的代碼就十分必要了。幸運的是，數據科學家可以采用軟件工程中的優秀實踐，本文也將對其進行介紹。

注意：本文主要討論Python，因為它是目前為止工業數據科學中應用最廣泛的語言。在Python中：

• 變量名/函數名小寫并且用下劃線隔開
• 命名常數的名稱全部大寫
• 類的名稱采用駝峰式大小寫命名規則

命名變量

命名變量時要記住三個基本原則：

• 變量名必須描述變量所表示的信息。變量名應該用詞明確，來體現變量代表的內容。
• 代碼讀取的次數將多于編寫的次數。所以優先考慮代碼的可讀性而不是編寫速度。
• 采用標準的命名規范，才可以做出一個全局決策，而不是做出多個局部決策。

在實踐中又如何呢?下面對變量名進行一些改進：

• x和y。如果多次閱讀了解的話會知道它們是特性和目標，但是對于閱讀代碼的其他開發人員來說，這可能并不明確。相反，要使用可以描述這些變量含義的名稱，如house_features和house_prices。
• value。value代表什么?它可以是velocity_mph, customers_served, efficiency, revenue_total。像value這樣的名稱并不能體現變量的用途，而且容易混淆。
• temp。即使只將變量用作臨時值存儲，也要給它一個有意義的名稱。這可能是用于轉換單位的值，因此在這種情況下，請明確說明：

# Don't do this 
temp = get_house_price_in_usd(house_sqft, house_room_count) 
final_value = temp * usd_to_aud_conversion_rate 
 
# Do this instead 
house_price_in_usd = get_house_price_in_usd(house_sqft, 
                                           house_room_count) 
house_price_in_aud = house_price_in_usd * usd_to_aud_conversion_rate 

• 如果使用縮寫，如usd, aud, mph, kwh, sqft，請確保提前和團隊其他成員約定好常用的縮寫，并進行書面記錄。然后在代碼審查中，確保執行這些書面標準。
• tp,tn,fp,fn:避免特定的機器學習縮寫。這些值表示true_positives、true_negative、false_positives和false_negative，因此明確說明它們的含義。除了難以理解之外，較短的變量名也可能產生鍵入錯誤。當想要輸入tn時，較容易寫成tp，所以請完整地描述。
• 上例說明要優先考慮代碼的易讀性，而不是代碼的編寫速度。比起優良的代碼，閱讀、理解、測試、修改和調試低質量的代碼花費更長時間。總的來說，通過使用更短的變量名來更快地編寫代碼，實際上會增加程序的開發時間!不相信的話，請拿出6個月前寫的代碼，并嘗試修改。如果發現難以理解自己的代碼，這表明你應該遵守更好的命名規定。
• xs和ys。這些值通常用于繪圖，在這種情況下，值代表x_cordinates和y_cordinates。但是，這些名稱也會用于許多其他任務，因此可以通過使用描述變量用途的特定名稱來避免混淆，例如times和distances或temperatures以及energy_in_kwh。

造成不良變量名的原因

[[285900]]

命名變量的問題大多數來源于：

• 試圖縮短變量名
• 直接將公式轉寫為代碼

關于第一點，雖然像Fortran這樣的語言確實限制了變量名的長度(6個字符以內)，但現代編程語言沒有限制，所以不要強迫自己使用縮寫。也不要使用過長的變量名，但是如果一定要做出選擇，要力求可讀性。

關于第二點，當編寫方程或使用模型時——這是學校忘記強調的一點——記住字母或輸入代表實際值!

下列是一個同時犯了兩種錯誤的例子及其改正方式。假設有一個從模型中得出的多項式能夠求出一所房子的價格。開發者可能會想直接用代碼編寫數學公式：

temp = m1 * x1 + m2 * (x2 ** 2) 
final = temp + b 

這段代碼看起來像是由機器為機器編寫的。雖然計算機最終會運行此代碼，但人類進行讀取的次數更多，所以編寫能讓人類理解的代碼!

要做到這一點，并不需要考慮公式本身——怎么做——而需要考慮建模的真實對象——是什么。下面是完整的等式(這能很好地測試讀者是否理解了模型)：

house_price = price_per_room * rooms + \ 
              price_per_floor_squared *(floors ** 2) 
house_pricehouse_price = house_price + expected_mean_house_price 

如果命名變量時遇到困難，意味著對模型或代碼的不了解。編寫代碼是為了解決實際問題，所以需要理解模型采集的目標。描述性變量名有助于在比公式更高的抽象級別工作，以及幫助開發者關注問題本身。

其他注意事項

命名變量時重要的一點是一致性計數。使用一致的變量名可以減少命名時間，增加解決問題的時間，尤其是添加復合性變量名時。

1. 變量名中的聚合

讀者已經了解使用描述性名稱的基本思想，將 xs更改為distances，將e 更改為efficiency，將v更改為 velocity。那么求平均速度該使用什么樣的變量名?是average_velocity, velocity_mean 還是velocity_average?下列步驟可以解決這個問題：

• 首先，確定常用縮寫:avg表示平均值，max表示最大值，std表示標準差等等。確保團隊的所有成員達成一致，并把這些記錄下來。
• 把縮寫放在變量名的末尾。將最具相關性的信息，即變量所描述的實體，放在開頭。

按照這些規則，聚合變量可能被命名為為velocity_avg, distance_avg, velocity_min,以及 distance_max。第2條可以依據個人情況酌情選擇。

當一個變量表示一個項目的數量時，就會出現一個棘手的問題。如要使用building_num，那么它是指建筑物的總數，還是特定建筑物的某個索引值?為了避免歧義，使用building_count表示建筑物總數，使用building_index表示特定建筑物。這也適于其他問題，如item_count和item_index。item_count也可用item_total代替。這種方法解決了歧義，并保持了將復合名稱添加在名稱末尾的一致性。

2. 循環索引

非常不幸，典型的循環變量已經變成i、j和k。這可能是造成數據科學中最多錯誤和困擾的原因。將無說明性的變量名與嵌套循環結合起來(筆者見過使用ii、jj甚至iii的嵌套循環)，就會產生不可讀、容易出錯的代碼。這一點可能有些爭議，但筆者從不使用i或任何其他單個字母作為循環變量，而是選擇描述迭代的內容，例如

for building_index in range(building_count): 
   .... 

或

for row_index in range(row_count): 
    for column_index inrange(column_count): 
        .... 

這格外適用于嵌套循環，此時無需記憶i是代表行還是列，或者與j和k混淆。應該花更多腦力來思考如何創建最佳模型，而不是數組索引的具體順序。

(在Python中，如果不使用循環變量，則應使用下劃線“_”作為占位符。這樣就不會對是否使用了索引感到困惑。)

3. 其他需要避免的命名方式

• 避免在變量名中使用數字
• 避免易拼錯的單詞
• 避免使用不明確的字符
• 避免使用含義相似的變量名
• 避免使用縮寫
• 避免發音相似的變量名

應堅持優先考慮可讀性而不是方便性這一原則。編程主要是為了與其他程序員進行溝通，因此請適當考慮團隊成員。

不使用魔數

[[285903]]

魔數是指未命名的常量。它常被用于單位轉換，改變時間間隔或增加下標時：

final_value = unconverted_value * 1.61   
final_quantity = quantity / 60   
valuevalue_with_offset = value + 150  
（這些變量名都很糟糕！） 

魔數會導致大量的錯誤和混亂，因為：

• 只有作者本人知道魔數的含義
• 改變魔數的值需要查找它出現的所有位置，然后人工輸入新值

可以定義一個用于轉換的函數來代替魔數。這個函數接受一個未經轉換的值以及一個轉換率作為參數。

defconvert_usd_to_aud(price_in_usd,            
                      aud_to_usd_conversion_rate): 
    price_in_aus = price_in_usd *usd_to_aud_conversion_rate 

如果要在一個項目的許多函數中使用同一個轉換率，可以在某處定義一個命名常量。

USD_TO_AUD_CONVERSION_RATE = 1.61   
price_in_aud = price_in_usd * USD_TO_AUD_CONVERSION_RATE 

(在開始編寫這個項目之前，需要和其他組員約定usd代表美元，aud代表澳元。記住標準!)

下面是另一個例子：

# Conversion function approach 
def get_revolution_count(minutes_elapsed,                       
                        revolutions_per_minute): 
    revolution_count = minutes_elapsed *revolutions_per_minute 
 
# Named constant approach 
REVOLUTIONS_PER_MINUTE = 60 
  
revolution_count = minutes_elapsed *REVOLUTIONS_PER_MINUT 

使用在某處定義的命名常量使得改寫數值更加容易和一致。如果轉換率發生改變，無需搜索整個代碼庫來改變它每次出現時的值，因為它只在一處被定義。這也把常數的含義告訴了代碼的讀者。如果參數名能夠體現參數的內容，函數參數也是一個可行的解決方式。

一個魔數缺陷的實例來自于筆者在大學時從事的某個研究項目。這個項目需要獲取每15分鐘更新的能量數據。沒有人想到這個數字可能會變化，于是團隊編寫了大量使用魔數15的函數(或者96，即每日觀測次數)。這些函數運行得很好，直到開始以5分鐘和1分鐘的間隔獲取數據。整個團隊花費了幾周的時間來修改函數，使它們能夠接受一個時間間隔作為參數。即使這樣，還是遇到了很多由于幾個月以來使用魔數而導致的錯誤。

真實的數據經常改變，比如匯率每分鐘都在變化。強行使用具體的數值來編程意味著可能不得不花費大量時間重寫代碼和修復錯誤。編程中沒有“魔法”的位置，即使是在數據科學中也是如此。

標準和約定的重要性

使用標準的好處在于它們幫助開發者簡單地做出全局決策而不是許多的局部決策。無需在每次命名變量時選擇聲明的位置，而是在項目開始的時候做好決定，然后在整個項目中前后一致地使用這些變量。這樣做的目的是花費更少的時間在命名、格式和風格這類數據科學的非核心問題上，用更多的時間解決重要的問題(比如使用機器學習研究環境變化)。

習慣獨自工作的開發者可能很難意識到采用標準的優越性。然而即使是獨自工作，也可以練習定義自己的規則并且一貫地使用它們。開發者將能夠少做一些瑣碎的決定，并且這也是為將來進行團隊開發工作做準備。在任何需要一人以上的項目中，標準都是必要的。

讀者可能會質疑本文中的某些命名選擇，這無關緊要。更重要的是采用一組一貫的標準，而不是命名時具體使用的空間或者變量名的最大長度。關鍵是不再在偶然的難題中花費大量時間，而是專注于解決必然的問題。

結論

記住剛剛學到的，現在回到文章開頭的代碼：

for i in range(n): 
    for j in range(m): 
        for k in range(l): 
            temp_value = X[i][j][k] *12.5 
            new_array[i][j][k] =temp_value + 150 

然后使用描述性的變量名和符號常量對它進行修改。

PIXEL_NORMALIZATION_FACTOR = 12.5 
PIXEL_OFFSET_FACTOR = 150 
  
for row_index in range(row_count): 
   for column_index in range(column_count): 
       for color_channel_index in range(color_channel_count): 
            normalized_pixel_value = ( 
          original_pixel_array[row_index][column_index][color_channel_index] 
                * PIXEL_NORMALIZATION_FACTOR 
            ) 
           transformed_pixel_array[row_index][column_index][color_channel_index] =( 
                normalized_pixel_value + PIXEL_OFFSET_FACTOR 
            ) 

現在可以看出這段代碼是在規格化數組中的像素值，并且加上一個偏移量來建立一個新的數組(忽略這種實現的低效性!)。當這段代碼被交付給同事，他們將能夠讀懂和修改它。而且，當開發者回頭看這段代碼，試圖測試和修正錯誤，他們也將清楚地知道自己在做什么。

這個話題無聊嗎?或許有一點枯燥，但如果花費時間閱讀有關軟件工程的書目，會發現優秀程序員和普通程序員的區別就在于重復使用這些無趣的技巧，比如好的變量名、短暫的工作周期、測試每一行代碼、重構等等。這就是把代碼從實驗室級別提升到工業生產級別所需要的。并且一旦做到這一點，就能發現使用模型來改變現實生活中的決策非常有趣。

本文討論了一些改進變量名的方式。

需要牢記的所有重點：

• 變量名應該描述它所代表的對象
• 比起易編寫性更重視易讀性
• 在項目中使用一貫的標準，從而盡可能減輕瑣碎決定的識別難題。

特別要點：

• 使用描述性的變量名
• 使用函數參數或者命名常量而不是“魔數”
• 不要使用特定的機器學習縮寫
• 用變量名描述算式或模型的含義
• 把組合而成的變量名放在末尾
• 使用item_count而不是num
• 使用描述性的循環索引而不是i、j、k
• 在整個項目中采用統一的命名和格式規則