分析一套源代碼的代碼規範和風格並討論如何改進優化代碼

個人工程實踐課題是《手寫中文漢字識別》，涉及深度學習與神經網絡方面的知識，所以這裏我找了一份對路透社數據集進行文本分類的源碼，對其代碼規範和風格進行討論。

1.結合工程實踐選題相關的一套源代碼，根據其編程語言或項目特色，分析其在源代碼目錄結構、文件名/類名/函數名/變量名等命名、接口定義規範和單元測試組織形式等方面的作法和特色

源碼結構以下：

（因爲圖片太長無法所有截屏，我用python寫了一個拼接的小程序分兩次截屏而後拼起來了）

代碼中導入的庫有tensorflow、keras、numpy和 matplotlib，這都是一些經常使用的庫。其中keras框架是以tensorflow爲後端運行的。

文件名/類名/函數名/變量名等命名

文件名：文件名是我本身命名的，沒有實際意義。

類名：這個源代碼中並無定義類，不過在python中，類是面對對象編程中重要的概念，通常定義類的格式爲：

class 類名：

   def __init__(self):

      self.屬性=...

   def 方法(self,...):

      ......

和C++中類的定義類似，但更加簡單明瞭。

函數名：這份源代碼中只定義了一個函數vectorize_sequences()，其餘都是調用庫中的函數，好比「reuters.load_data()、reuters.get_word_index()、model.add()、plt.show()」等等。

變量名：這份源代碼中的變量格外的多，但爲了讀代碼的人更容易理解，取得名字會盡可能一目瞭然，好比「train_data[10]、train_labels[10]、model、x_val、y_val、val_loss」等等，看到變量名就能夠猜到用途。

接口定義規範和單元測試組織形式等方面的作法和特色

在python中接口主要的途徑就是導入，因此這裏分析在python語言中導入的規範。可見這裏導入的接口都寫在了源代碼的最前面，導入應該按照從最通用到最不通用的順序分組:

1.標準庫導入

2.第三方庫導入

3.應用程序指定導入

在python中，對單個文件進行測試的方法就是利用main函數，所以，代碼應該在執行主程序前老是檢查 if name == 'main' , 這樣當別的模塊被導入時主程序就不會被執行。

 

 2.列舉哪些作法符合代碼規範和風格通常要求

因爲本文源代碼是使用python書寫的，所以在這裏主要基於python語言的書寫規範和風格寫一寫：

Python語言規範

　　1. imports 僅僅用作包和模塊的導入，包的導入每一個儘可能獨佔一行

　　2. packages 導入模塊儘可能使用模塊的全路徑

　　3. Exceptions 必須當心使用

　　4. Global variables 避免使用全局變量

　　5. Generator 

　　6. lambda 函數僅僅適用於一行代碼能實現的簡單函數

　　7. True or False 儘可能使用[],'',{},0,None來隱式表示False

Python風格規範　

　　一、代碼編排

　　　　1 縮進：4個空格實現縮進，儘可能不使用Tab，禁止混用Tab和空格

　　　　2 行：每行最大長度不超過79，換行可使用反斜槓(\)。最好使用圓括號將換行內容括起來，不建議使用「;」

　　　　3 空行：類和top-level函數定義之間空兩行；類中的方法定義之間空一行；函數內邏輯無關段落之間空一行；其餘地方儘可能不要再空行。

　　　　4 空格：括號內的第一個位置，不要空格。緊靠右括號的位置也不要空格。冒號(:)、逗號(,)、分號(;)以前不要加空格。切片木有參數，不要加空格等

　　　　5 括號：對於單元素tuple必定要加,和括號

　　二、命名規範

　　　　module_name

　　　　package_name  

　　　　ClassName  

　　　　method_name  

　　　　ExceptionName

　　　　function_name

　　　　GLOBAL_CONSTANT_NAME

　　　　global_var_name

　　　　instance_var_name

　　　　function_parameter_name

　　　　local_var_name

　　三、註釋規範

　　　　

　　　　1.塊註釋，在一段代碼前增長的註釋。在‘#’後加一空格。段落之間以只有‘#’的行間隔。好比：

　　　　# Description : Module config. 　　　　# 　　　　# Input : None 　　　　# 　　　　# Output : None

　　　　2. 行註釋，在一句代碼後加註釋。好比：x = x + 1 # Increment x 可是這種方式儘可能少使用。

　　　　3. 避免無謂的註釋。

　　四、編程建議

　　　　1. 字符串拼接，儘可能使用join。使用str的方法而不是內置方法。使用startswith或endswith拉檢查前綴和後綴

　　　　2. 單例對象，儘可能使用is 、is not，不要使用==

　　　　3. 使用is not而不是not is

　　　　4. 使用def來定義函數，而不是將匿名函數賦給某個變量

　　　　5. 儘可能使代碼整齊，簡潔

　　　　6. 使用isinstance()來判斷instance的類型

 

3.列舉哪些作法有悖於「代碼的簡潔、清晰、無歧義」的基本原則，及如何進一步優化改進

對於python代碼來講，縮進的使用是很是重要的，合理使用縮進也使得代碼看起來簡潔明瞭，但縮進使用的不正確就會致使代碼產生歧義從而出錯。優化能夠經過單步調試程序來進行。

 

4.總結同類編程語言或項目在代碼規範和風格的通常要求

對於python程序而言：

 

   ·僅對包和模塊使用導入，即模塊間共享代碼的重用機制，命名空間管理約定十分簡單. 每一個標識符的源都用一種一致的方式指示. x.Obj表示Obj對象定義在模塊x中.

   ·使用模塊的全路徑名來導入每一個模塊，避免模塊名衝突. 查找包更容易。

   ·容許使用異常, 但必須當心。經過使用異常，咱們能夠在錯誤發生的時候繼續執行與這個錯誤無關的餘下代碼，維持程序的正常運行。

   ·避免使用全局變量，即定義在模塊級的變量，由於導入時可能會改變模塊行爲。

   ·鼓勵使用嵌套/本地/內部類或函數。

   ·使用單行函數時推薦使用條件表達式，簡化if語句。

   ·構建函數時鼓勵使用默認值。

   ·不要在行尾加分號, 也不要用分號將兩條命令放在同一行。

   ·每行不超過80個字符。

   ·寧缺毋濫的使用括號。

   ·用4個空格來縮進代碼，即懸掛縮進，此時第一行不該有參數。

   ·頂級定義之間空兩行, 方法定義之間空一行。好比類定義之間應該空兩行。

   ·按照標準的排版規範來使用標點兩邊的空格。一個函數必需要有文檔字符串好比：在逗號、分號後加空格；通常表達式在等號的兩端加空格；括號裏不要有空格等。

   ·確保對模塊, 函數, 方法和行內註釋使用正確的風格。好比：一個函數應該要有註釋，包含函數作什麼, 以及輸入和輸出的詳細描述。對於塊註釋（#）和行註釋（""" """）的使用，也要細心考量。

   ·最後着重說一下命名的規範：

    1）「Internal」表示僅模塊內可用, 或者, 在類內是保護或私有的.

    2）用單下劃線「_」開頭表示模塊變量或函數是protected的(使用from xxx import *時不會包含在內).

    3）用雙下劃線「__」開頭的實例變量或方法表示它是private的.

    4）將相關的類和頂級函數放在同一個模塊裏。

    5）對類名使用大寫字母開頭的單詞(如Car), 可是模塊名應該用小寫加下劃線的方式(如speed)。

    6）應避免：單字符名稱（除了計數器和迭代器）；包/模塊名中的連字符「-」；雙下劃線開頭並結尾的名稱。