分析一套源代码的代码规范和风格并讨论如何改进优化代码

源码下载：

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. 使用基本设计模式下降模块耦合，并对函数间数据流流向有较好把握和控制。