分析UIS-RNN源代码的代码规范和风格

结合工程实践选题相关的一套源代码，根据其编程语言或项目特点，分析其在源代码目录结构、文件名/类名/函数名/变量名等命名、接口定义规范和单元测试组织形式等方面的做法和特点；

列举哪些做法符合代码规范和风格一般要求；

列举哪些做法有悖于“代码的简洁、清晰、无歧义”的基本原则，及如何进一步优化改进；
总结同类编程语言或项目在代码规范和风格的一般要求。

我的工程实践题目是《多人对话场景中音频分离》，题目要求的任务即说话人区分（Speaker Diarization）任务。我找到了一套实现了说话人区分任务的算法代码，该算法被称为UIS-RNN，出自Google团队于2018年发表的论文 “Fully Supervised Speaker Diarization”。

代码要求

本文以uisrnn包文件为例，讨论该项目的命名风格。参考的命名规范是Google Python Style Guide，该文档是Google团队所用的代码规范，本项目的团队也是来自Google的。下文中将列举一些该规范中的代码风格要求，并且考察该项目的风格十分符合规范。

目录结构

可以看到，该项目和通常的 Github 项目一样，将说明文档、许可证等文件置于根目录，与运行相关的、需要用户直接使用的脚本文件也放在根目录。这些都是与用户直接接触的文件，放在根目录便于用户使用。

算法的核心部分放在uisrnn文件夹，该算法是基于Pytorch框架实现的，按照网络结构、代价函数、参数、工具函数等分为了几个不同的文件。

tests文件中存放了测试文件，data文件夹中存放了测试数据，此外，项目的一些宣传文档和资源被放在了docs文件夹和resources文件夹中。

本项目的目录组织比较合理，用户使用方便，相关的文件也得到了聚合。

命名

表中前三列是Google Python Style Guide中要求的，同时也是Python之父Guido推荐的规范的命名规范，第四列是该项目所用命名举例。

Type	Public	Internal	Examples
Modules	lower_with_under	_lower_with_under	uisrnn、utils
Packages	lower_with_under		uisrnn
Classes	CapWords	_CapWords	BeamState、UISRNN
Exceptions	CapWords		TypeError
Functions	lower_with_under()	_lower_with_under()	weighted_mse_loss
Global/Class Constants	CAPS_WITH_UNDER	_CAPS_WITH_UNDER	_INITIAL_SIGMA2_VALUE
Global/Class Variables	lower_with_under	_lower_with_under
Instance Variables	lower_with_under	_lower_with_under (protected) or __lower_with_under (private)	look_ahead
Method Names	lower_with_under()	_lower_with_under() (protected) or __lower_with_under() (private)	fit_concatenated、_calculate_score
Function/Method Parameters	lower_with_under		look_ahead_seq
Local Variables	lower_with_under

可以看到，本项目命名基本符合Google Python Style Guide的规范。项目中一些变量名为了可读性使用了较长的单词，很多变量名都很长，可读性有时反而会有所下降。

其他规范

参考Google Python Style Guide，下面列举了一些其他方面的代码规范，这些规范该项目基本都遵守了：

不要在行尾加分号, 也不要用分号将两条命令放在同一行。
每行不超过80个字符。
除非是用于实现行连接, 否则不要在返回语句或条件语句中使用括号。
用4个空格来缩进代码。
顶级定义之间空两行, 方法定义之间空一行。
括号内不要有空格。

注释

该项目严格按照代码规范的要求写了注释，包括函数文档、类文档、模块许可证，逻辑比较复杂之处还额外添加了行注释，对于使用者来说已经足够方便，但是如要理解代码，能再多写一些注释就更好了。

下面列举一些行注释的要求，该项目基本做到了：

最需要写注释的是代码中那些技巧性的部分。
为了提高可读性，注释应该至少离开代码2个空格。
绝不要描述代码。假设阅读代码的人比你更懂Python, 他只是不知道你的代码要做什么。

单元测试

该项目对核心模块uisrnn.py、utils.py、evals.py都按模块生成了单元测试文件，保证了每个模块能够正常工作。

总结

该项目风格严谨，命名规范，注释详尽合理，此种代码风格值得我们学习。