基于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”语句 以管理文件。