基于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的开源项目风格指南，变量 (包括函数参数) 和一律小写, 单词之间用下划线连接。回过头来看这个开源项目的风格，里面的变量命名基本是不规范的。

函数命名及定义规范

一般的，常规函数使用大小写混合, 取值和设值函数则要求与变量名匹配。而且一个函数必须要有文档字符串，除非它满足以下条件:
1、外部不可见

2、非常短小

3、简单明了

文档字符串应该包含函数做什么, 以及输入和输出的详细描述.通常, 不应该描述”怎么做”, 除非是一些复杂的算法。函数文档字符串应该包括以下内容：

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