标签：函数 代码 规范 注释 索引 使用 命名

规范分类

● 代码格式
● 命名规范
● 注释规范
● 其他注意
● 数据库规范
● 接口规范
● 测试规范

代码格式

强制：

1. 代码缩进为4个空格，每行最大长度为79
2. import 一次导入一个模块
3. 使用两个空行分割fun和class，使用一个空行分割class中的method
4. 空格规则：
   a. 在二元运算符两边都要有空格。二元运算包括：算术(+ - * / ** )、赋值(=，+=，-=)、比较( ==, <, >, !=, in, not in, is, is not)、逻辑运算(and or not)、位运算(& | ! ~ >> <<)。
   b. 函数的参数时=两侧不需要空格
   c. 逗号后面要加空格，例外：但是如果后面是小括号则不用
   d. 冒号前不加空格，冒号后要加空格。例外：切片里前后都不用加空格
5. 使用枚举类型进行条件筛选时，必须使用==、in、!=运算符，禁止使用<、>。
6. 注释的# 与注释内容之间有且只有一个空格

推荐：

1. 代码中的数字不要意义不明，有些特殊意义的数字可以写在常量文件中并备注。如 if plan_id in [1, 4] 这里的1 4 给人意义不明
2. 单个方法总行数不得超过80行
3. 出现三处及以上功能相同的代码，要考虑重构复用
4. 避免使用函数内 import 解决循环依赖,以 import 整个路径形式解决，同时要知道函数内加载包会使运行缓慢
5. 0表示否/无/失败的意思，而1表示有/对/成功的意思，我们在app/constants 中定义YES和NO常量，用来表示布尔值
6. 避免在函数内声明函数，每次运行时都会给内置函数分配内存且垃圾回收，影响执行效率
7. 批量处理时，使用try来保证发生错误不对后续处理造成影响

命名

强制：

1. 包名文件名以小写+下划线命名，类名以大写开头驼峰命名，函数名以小写+下划线命名
2. 命名下划线最多不超过四个，命名长度不要超过25个字符
3. 代码中的命名不能以 $ 符号开始和结束，尽量少的以特殊符号命名
4. 代码中禁止使用拼音与英文混合的方式，更不允许直接使用中文命名
5. 常量名全部大写，单词间用下划线隔开
6. 在可接受的长度范围内，变量名能把它所指向的内容描述的越精确越好，尽量不要用那些过于宽泛的词来作变量名 ---正例：user_checkin_date ---反例：date
7. 使用is，has， allow，use等开头来命名表示boolean类型的元素

推荐：

1. 命名尽可能的统一，避免出现相同意义不同写法的命名 ---反例：一个课程命名为xxclass,一个为xxcourse
2. 变量名称不用太短，但是可以使用 i，j， k放在迭代器或生成式中使用

注释

强制

1. 逻辑复杂，难以理解，脚本代码等情况必须要有注释
2. 临时性解决，未来可删除的代码，必须有TODO注释 如：# TODO：代码临时迁移，10-12后删除
3. 函数注释在函数内第一行写，注释超过四行要使用"""xxx""" 去注释
   ---使用：def fun(): # 这是注释def fun2(): """ 注释1 注释2 注释3 注释4 """
4. 函数注释必须说明函数作用和特殊说明 ---使用：def get_user_info(user_id): # 获取用户基本信息def get_user_info(user_id): """parma: user_id int 用户ID return: dict 用户基本信息 获取用户基本信息 注：Date信息格式为String """
5. 代码修改修复，要同步更新注释

推荐

1. 注释不是越长越好，简单易懂，支持中文和英文
2. 注释掉代码需在上方说明，否则可以直接删除无用代码

其他

1. 根据MVC架构，项目的views模块中的代码尽量不要做逻辑处理
2. 项目相关的配置应放在configs目录下，业务相关的配置应放在业务module内（例如constants.py）
3. 函数返回时，如果有错误直接报错，不要返回把错误作为返回值返回
4. 推荐清理不再使用的代码段或者配置信息

MySQL数据库

思想

1. 评估是否扩展表结构，扩展后的优点和缺点
2. 确定好扩展带来的风险，扩展的最优方案
3. 在执行扩展指令或者JOB时，减少对用户产生的影响，放在用户低峰期去执行
4. 数据量大的表，尽可能和多人协商出一个扩展方案

强制

1. 必须在代码中体现table_name
2. 表名不使用复数名词
3. 禁用保留字作为表名，建议不要作为字段名，MySQL保留字文档： https://dev.mysql.com/doc/refman/8.0/en/keywords.html
4. 禁止使用float和double字段存储数据
5. 设计表必须满足1NF，JSON字段除外
6. 表中出现别的表的主键ID必须以_id结尾，且必须设置对应的类型
7. 表中出现其他表出现的字段，必须和其他表字段类型相同
8. 业务具有唯一特性字段，即使存在多个字段也必须建立唯一索引
9. varchar字段上加索引需要指定索引长度，如无法指定长度不要在varchar字段加索引
10. 使用is_xxx方式命名字段，表示布尔值，且只取0，1。定义为tinyint, peewee对应的为 BooleanField 使用：
    # 正确 is_checkin = peewee.BooleanField(default=False)
    # 错误 status = peewee.BooleanField(default=False)
11. 尽量不使用BigInt去存储数据，目前已知的BigInt类型的有 user_id
12. smallint 长度为65535。保存枚举数据时可以使用smallint， peewee对应的为 SmallIntegerField
13. 查询超过1000条数据时，使用分页查询
14. 执行DDL前依据数据量级、操作类型评估风险，然后决定执行策略。依据风险大小可以选择直接执行，流量低峰期执行或复制表+双写等操作
15. 不允许创建外键，需求外键逻辑的场景应使用代码实现

推荐

1. 接口中不要直接count/sum/average整表，可以使用缓存或者表达式计算假数据等方式
2. 一行中出现的varchar长度最多为65535，在使用时确定好自己使用varchar的长度，及时换成TextField
3. 用户数据表尽可能设计的简洁，设计好每一个字段
4. CharField字段默认max_length=255, 使用时根据需求设置127， 1023等
5. 查询频率高，代码逻辑复杂，考虑添加缓存缓解数据库压力
6. 插入数据时，需要被校验的字段，使用validates装饰器
7. 某些不必填写的内容，使用default取默认值
8. 有order_by使用场景，请注意使用索引的有序性，最左原则
9. 建立组合索引时，区分度最高的在最左边
10. 大批量的分页查询，避免使用limit offset（peewee）语句，建议记录上一次查询的主键，下次查询使用主键作为条件查询
11. 分页查询不再返回count字段
12. 当索引的字段超过三个时，使用hash创建唯一索引标识
13. 创建索引时避免有如下极端误解：1）宁滥勿缺。认为一个查询就需要建一个索引。2）宁缺勿滥。认为索引会消耗空间、严重拖慢更新和新增速度。3）抵制惟一索引。认为业务的惟一性一律需要在应用层通过“先查后插”方式解决
14. 改变表结构时先把命令全部写好，在操作时直接复制运行避免出问题

个人总结

错误捕获原则：错误捕获越精细越好，颗粒度要以行为单位，每次捕获一行代码的错误

尽量减少局部变量，可以写在函数中变量要写在函数中。前提是不能让函数膨胀
类中使用超过2次变量考虑抽象出来封装成一个类的属性，方便统一修改

数据库更新要使用save方法，save的同时会更新update_at，同时save要指明字段
批量插入要使用批量的方法，不能用循环插入

底层函数要通用，不要携带调用方的业务信息。如数据库里的函数要通用，不能只给某一个调用方创建一个函数
区分前端和后端错误，对于前端传入的找不到的错误抛给前端

标签：函数,代码,规范,注释,索引,使用,命名
来源： https://www.cnblogs.com/goldsunshine/p/16559609.html

本站声明： 1. iCode9 技术分享网（下文简称本站）提供的所有内容，仅供技术学习、探讨和分享；
2. 关于本站的所有留言、评论、转载及引用，纯属内容发起人的个人观点，与本站观点和立场无关；
3. 关于本站的所有言论和文字，纯属内容发起人的个人观点，与本站观点和立场无关；
4. 本站文章均是网友提供，不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属；如您发现该文章侵犯了您的权益，可联系我们第一时间进行删除；
5. 本站为非盈利性的个人网站，所有内容不会用来进行牟利，也不会利用任何形式的广告来间接获益，纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。