分析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都按模块生成了单元测试文件，保证了每个模块能够正常工作。
总结
该项目风格严谨，命名规范，注释详尽合理，此种代码风格值得我们学习。
