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

源碼下載：

git clone https://github.com/lemonhu/stock-knowledge-graph.git

stock-knowledge-graph

A small knowledge graph (knowledge base) construction using data published on the web.
利用網絡上公開的數據構建一個小型的證券知識圖譜（知識庫）。

tree:

├── build_csv.py
├── data
│   ├── executive_prep.csv
│   ├── import
│   │   ├── concept.csv
│   │   ├── executive.csv
│   │   ├── executive_stock.csv
│   │   ├── import.report
│   │   ├── industry.csv
│   │   ├── stock_concept.csv
│   │   ├── stock.csv
│   │   └── stock_industry.csv
│   ├── stock_concept_prep.csv
│   ├── stock_industry_prep.csv
│   └── stockpage.zip
├── design.png
├── extract.py
├── img
│   ├── executive_detail.png
│   ├── executive.png
│   └── stock_graph_demo.png
├── import.report
├── import.sh
├── LICENSE
├── README.md
├── requirements.txt
├── result.txt
├── Review prediction with Neo4j and TensorFlow.md
├── ssr.sh
└── stock.py

├── data：處理好的neo4j關係型數據庫數據集

│ ├── import：以csv格式保存的關係型數據庫預處理數據集

├── img：媒體文件，以圖片文件爲主

├── build_csv.py ：從預處理csv創建csv處理後數據集

├── extract.py：提取公司或者股票中的經理

├── stock.py：獲取並保存股票上市公司行業分類信息、獲取並保存股票上市公司行業概念信息

文件名函數命名規範：

extract、build_csv、 stock_concept_prep.csv、stock_concept.csv、Review prediction with Neo4j and TensorFlow.md

等均使用較爲準確描述其功能的小寫字母命名，除了readme文件，均以短下劃線爲分割，清晰易懂。如stock_concept_prep.csv，令人準確知道這是股票與概念之間聯繫預處理數據集的csv文件。stock_graph_demo.png令人準確知道這是股票演示圖的示範圖片文件，對於媒體文件的準確命名是不少項目疏忽或者難以耗費精力完成的地方，做者對媒體文件命名規範準確可貴。

類命名延續了文件命名小寫字母+下劃線分割的作法，build_executive表示創建能夠被neo4j識別的csv文件，清晰易懂。下劃線法是c出現後開始流行起來的，在許多舊的程序和UNIX這樣的環境中，它的使用很是廣泛。

接口規範：

接口不只有對函數功能的說明，也有對參數類型及內容的描述。

def extract(stockpage_dir, executive_csv):
    """Extract executive of the comnpany or stock

    Args:
        stockpage_dir: (str) the directory of stock pages
        executive_csv: (str) the full path of the CSV file to be saved
    """

stockpage_dir = './data/stockpage'
directors_csv = './data/executive_prep.csv'
extract(stockpage_dir, directors_csv)

def get_md5(string):
    """Get md5 according to the string
    """
    return restult #string type

def build_executive(executive_prep, executive_import):
    """Create an 'executive' file in csv format that can be imported into Neo4j.
    format -> person_id:ID,name,gender,age:int,:LABEL
    label -> Person
    """
    return None

def build_stock(stock_industry_prep, stock_concept_prep, stock_import):
    """Create an 'stock' file in csv format that can be imported into Neo4j.
    format -> company_id:ID,name,code,:LABEL
    label -> Company,ST
    """

def build_concept(stock_concept_prep, concept_import):
    """Create an 'concept' file in csv format that can be imported into Neo4j.
    format -> concept_id:ID,name,:LABEL
    label -> Concept
    """

單元測試組織形式

做者將工程切割爲6個單元分別測試，模塊間耦合性在做者代碼重構下被分爲多個文件後有所下降，可單獨進行測試：

從⽹頁中抽取董事會的信息、獲取股票行業和概念的信息、設計知識圖譜、建立能夠導⼊Neo4j的csv文件、

利用上面的csv文件生成數據庫、基於構建好的知識圖譜，經過編寫Cypher語句回答以下問題。

使用logs:記錄出錯詳細信息，便於分析：

Id '50371a2c5078b757a8f8c75b8877e815' is defined more than once in group 'global id space'

使用requestments，指導其餘用戶測試時快速搭建環境：

lxml
pandas
beautifulsoup4
tushare

使用beta測試改進兩個用戶提交的錯誤：

1.IndexError: list index out of range

2.Id 'xxx' is defined more than once in group 'global id space'

基於MD5的實體惟一性肯定規則，這裏的兩個姚波應該屬於同一我的，不該該有重複的ID(實際上重複也不會有影響)。

相關規範：

開頭有了coding: utf-8 防止中文顯示亂碼

用4個空格來縮進代碼，不要tab和空格混用. 對於行鏈接,垂直對齊換行的元素

一個函數必需要有文檔字符串除非他對外部不可見或者非長短小。文檔字符串應記錄函數該怎麼作、不應怎麼作、對詳細算法的說明、輸入參數、輸入參數等。

文檔字符串應該提供足夠的信息, 當別人編寫代碼調用該函數時, 他不須要看一行代碼, 只要看文檔字符串就能夠了. 對於複雜的代碼, 在代碼旁邊加註釋會比使用文檔字符串更有意義.

關於函數的幾個方面應該在特定的小節中進行描述記錄， 這幾個方面以下文所述. 每節應該以一個標題行開始. 標題行以冒號結尾. 除標題行外, 節的其餘內容應被縮進2個空格.

• Args:

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

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

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

• Raises:

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

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

​ 1. 部分模塊沒有使用面向對象的思想，個別變量命名只有一個單詞，表意不夠直觀。

　2. 對函數接口沒有返回類型要求的描述，代碼讀者須要從函數調用實際狀況觀察。接口不徹底統一，沒法直接生成接口幫助文檔。

​ 3. 對於各個模塊沒有完整的註釋，儘管劃分模塊下降耦合但模塊間依然存在多種依賴關係。

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

1. 文件目錄清晰合理，文件命名基本體現文件功能。

2. 文件或函數接口命名採用駝峯或下劃線命名。

3. 文檔內容縮進合理，不能空格tab混用。

4. 開頭加上coding: utf-8 防止中文顯示亂碼

5. 函數接口有參數內容類型和返回類型說明，有對函數說明，最好能生成統一性文檔

6. 使用基本設計模式下降模塊耦合，並對函數間數據流流向有較好把握和控制。