基於Google開源項目風格指南的源代碼風格分析

基於Google開源項目風格指南的源代碼風格分析

我這次的工程實踐選題是金融方向的文本數據挖掘，因此在github上找了於此相關的開源項目，該開源項目是基於分佈式爬蟲，採集互聯網公開來源的金融類新聞，並在此基礎上進行數據分析。
本文選取這個開源項目的金融類文本情感分析這部分進行源碼風格的分析。

文件結構

通常的，要想了解一個github上的開源項目，首先都會去翻看該項目的README文件，由於這個小小的靜態文件其實傳達了整個項目的概述，如項目的介紹、代碼實現的功能、系統環境參數、部署要素等。
因此一個好的README文件應該包括如下內容：

1.項目簡介

2.功能特性

3.環境依賴

4.部署步驟

5.目錄結構描述

6.版本內容更新

7.聲明

8.協議

而在這個開源項目中包含了快速開始、使用方法、目錄結構描述和聯繫方式，雖然也可以對項目有個大概的瞭解，但README文件能夠寫得再詳細一些.
好比一些具體的實現原理或者項目的運行結果示例等，既能下降開源項目的使用門檻也能增長吸引力。

命名規範

通常來講，不論是函數命名、變量命令仍是文件命名都要有描述性，不要用只有項目開發者能理解的縮寫，也不要經過砍掉幾個字母來縮寫單詞，由於這樣作都會增長新讀者的閱讀理解的成本,
而使用描述性的命名可讓新讀者更易於理解代碼的含義，固然一些特定的廣爲人知的縮寫是容許的, 例如用 i 表示迭代變量和用 T 表示模板參數。

文件命名

根據Google的開源項目風格，文件名要所有小寫, 能夠包含下劃線 () 或連字符 (-), 使用 「」 更好。那麼咱們如今再回過頭來看這個開源項目，發現裏面有些文件的命名是符合命名規範的，有些是不符合的。在clean_data下符合文件命名規範的有：clean_html.py,zh_wiki.py，不符合的有：langconv.py，並且還使用了縮寫。

普通變量命名

一樣地，根據的Google的開源項目風格指南，變量 (包括函數參數) 和一概小寫, 單詞之間用下劃線鏈接。回過頭來看這個開源項目的風格，裏面的變量命名基本是不規範的。

函數命名及定義規範

通常的，常規函數使用大小寫混合, 取值和設值函數則要求與變量名匹配。並且一個函數必需要有文檔字符串，除非它知足如下條件:
一、外部不可見

二、很是短小

三、簡單明瞭

文檔字符串應該包含函數作什麼, 以及輸入和輸出的詳細描述.一般, 不該該描述」怎麼作」, 除非是一些複雜的算法。函數文檔字符串應該包括如下內容：

Args:

      列出每一個參數的名字, 並在名字後使用一個冒號和一個空格, 分隔對該參數的描述.
若是描述太長超過了單行80字符,使用2或者4個空格的懸掛縮進(與文件其餘部分保持一致). 描述應該包括所需的類型和含義.。
若是一個函數接受*foo(可變長度參數列表)或者**bar (任意關鍵字參數), 應該詳細列出*foo和**bar。

Returns: (或者 Yields: 用於生成器)

      描述返回值的類型和語義. 若是函數返回None, 這一部分能夠省略。

Raises:

      列出與接口有關的全部異常。

在該開源項目中吧，這部分作得比較好。

接口定義規範

在python中接口主要的途徑就是導入，因此這裏分析在python語言中導入的規範。通常的，根據google開源項目風格指南，導入總應該放在文件頂部,
位於模塊註釋和文檔字符串以後, 模塊全局變量和常量以前. 導入應該按照從最通用到最不通用的順序分組:

1.標準庫導入

2.第三方庫導入

3.應用程序指定導入

每種分組中, 應該根據每一個模塊的完整包路徑按字典序排序, 忽略大小寫。而在這方面上該開源項目沒有作好。

單元測試組織形式

在python中，對單個文件進行測試的方法就是利用main函數，根據谷歌開源項目風格指南對於main函數的規範以下：

在Python中, pydoc以及單元測試要求模塊必須是可導入的. 你的代碼應該在執行主程序前老是檢查 if name == 'main' , 這樣當模塊被導入時主程序就不會被執行。

def main():

      ....

if name == 'main':

      main()

全部的頂級代碼在模塊導入時都會被執行. 要當心不要去調用函數, 建立對象, 或者執行那些不該該在使用pydoc時執行的操做.

同類代碼的通常要求

建議參照谷歌的開源項目風格指南來養成本身的代碼風格，一來方便別人閱讀，二來能鍛鍊本身的代碼風格，好的代碼風格對提升編程能力是有幫助的。
谷歌開源項目風格指南裏面包含了C++、Objective-C、Python、JSON和Shell的風格指南。 在這裏特別指出註釋應該注意的地方：python中最須要寫註釋的是代碼中那些技巧性的部分。 若是開發者在下次代碼審查的時候必須解釋一下, 那麼開發者應該如今就給它寫註釋。 對於複雜的操做, 應該在其操做開始前寫上若干行註釋。對於不是一目瞭然的代碼, 應在其行尾添加註釋。爲了提升可讀性, 註釋應該至少離開代碼2個空格。 還有推薦使用 「with」語句 以管理文件。