总结同类编程语言或项目在代码规范和风格的一般要求
我做的项目是基于语音识别的人工智能问答系统,在GitHub上找了一套代码
源代码分析:
目录结构
命名合理,格式规范。
代码分析
选取其中一个函数分析。可以看到在变量命名、函数命名方面符合规范要求,仅有部分运算符号两侧未全部加空格。最后的return语句行过长,超过80字符应当分行。
块注释部分简洁明了,重点突出。导入部分应当每行导入一个模块,最好不要一行传入多个。
代码书写一般规范:
代码格式
1.统一使用 4 个空格进行缩进
2.每行代码尽量不超过 80 个字符(在特殊情况下可以略微超过 80 ,但最长不得超过 120)
3.自然语言使用双引号,机器标示使用单引号,文档字符串 (docstring) 使用三个双引号
4.模块级函数和类定义之间空两行,类成员函数之间空一行;
注释
1.块注释: “#”号后空一格,段落件用空行分开(同样需要“#”号)
2.行注释: 至少使用两个空格和语句分开,注意不要使用无意义的注释,在代码的关键部分(或比较复杂的地方), 能写注释的要尽量写注释 比较重要的注释段, 使用多个等号隔开, 可以更加醒目, 突出重要性
3.文档注释(Docstring):不要在文档注释复制函数定义原型, 而是具体描述其具体内容, 解释具体参数和返回值等。
4.作为文档的Docstring一般出现在模块头部、函数和类的头部,这样在python中可以通过对象的__doc__对象获取文档. 编辑器和IDE也可以根据Docstring给出自动提示. 文档注释以 """ 开头和结尾, 首行不换行, 如有多行, 末行必需换行
5.文档注释不限于中英文, 但不要中英文混用 文档注释不是越长越好, 通常一两句话能把情况说清楚即可 模块、公有类、公有方法, 能写文档注释的, 应该尽量写文档注释
命名规范
1.模块尽量使用小写命名,首字母保持小写,尽量不要用下划线
2.类名使用驼峰(CamelCase)命名风格,首字母大写,私有类可用一个下划线开头‘’_‘’
将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块.
3.函数名一律小写,如有多个单词,用下划线隔开
私有函数在函数前加一个下划线‘’_‘’
4.变量名尽量小写, 如有多个单词,用下划线隔开
常量采用全大写,如有多个单词,使用下划线隔开