python-33-python编码规范

python编码规范
Python 编码规范(Google)
提高代码可读性：Python 代码风格规范推荐

1 基本规范

一、代码编码
1、国际惯例，文件编码和Python编码格式全部为utf-8 ，例如：在Python代码的开头，要统一加上。

python设置文件编码的方式：
1、使用#coding=<编码名称>的方式设置；
2、使用#-*- coding: <编码名称> -*-的方式设置；

# coding=utf-8
# -*- coding: UTF-8 -*-
# -*- coding: utf-8 -*-
作用是定义源代码的编码.
如果没有定义, 此源码中是不可以包含中文字符串的.
sys.getdefaultencoding()查看系统默认编码

在python2中的文件中如果要填写中文，必须要加一行代码用来声明文件编码的注释，否则python2会报错，因为它默认的编码格式是ASCII。而在python3中已经没有这个问题了，python3默认的文件编码是UTF-8。

二、命名规范

1、包名、模块名、局部变量名、函数名
全小写+下划线式驼峰 示例：this_is_var

2、全局变量
全大写+下划线式驼峰 示例：GLOBAL_VAR

3、类名
首字母大写式驼峰 示例：ClassName()

4、变量名命名
尽量体现变量的数据类型和具体意义。
变量名、类名取名必须有意义，严禁用单字母。
变量名不要用系统关键字，如 dir type str等等。
bool变量一般加上前缀 is_ 如：is_success。

三、import 顺序

1、标准库   
2、第三方库  
3、项目本身
(之间用空行分隔)

四、models内部定义顺序

1、All database fields
2、Custom manager attributes
3、class Meta
4、def (str)
5、def save()
6、def get_absolute_url()
7、Any custom methods

五、异常捕获处理原则

1、尽量只包含容易出错的位置，不要把整个函数try catch。
2、对于不会出现问题的代码，就不要再用 try catch了，只捕获有意义，能显示处理的异常。
3、能通过代码逻辑处理的部分，就不要用try catch。
4、异常忽略，一般情况下异常需要被捕获并处理，但有些情况下异常可被忽略，只需要用log记录即可，可参考一下代码：

def ignored():
    try:
        yield
    except Exceptions as e:
        logger.warning(e)
        pass

六、return early原则
提前判断并return，减少代码层级，增强代码可读性(简单逻辑往前放)。

if not condition:
    return
# a lot if code

七、Fat model， thin view
逻辑代码和业务代码解耦分离，功能性函数以及对数据库的操作定义写在models里面，业务逻辑写在view里面。

八、权限校验装饰器异常抛出问题
建议权限不足时直接抛出异常，可以使用django自带的：权限不足时抛出异常PermissionDenied，之后应该返回什么样的页面由 handler 或者中间件去处理。

from django.core.exceptions import PermissionDenied

九、分method获取request参数问题
一般可以分method获取request参数，这样能够使代码更可读，且之后修改method时不必每个参数都修改。

args = request.GET if request.method == "GET" else request.POST
business_name = args.get('business_name', '')
template_name = args.get('template_name', '')

十、使用数字、常量表示状态
两种的话改为true/false，多种改为enum可读性更好

def enum(**enums):
    return type("Enum", (), enums)

StatusEnum = enum(
    SUCCESS=True,
    FAIL=False,
)

十一、其他注意问题

1、【必须】去除代码中的print，否则导致正式和测试环境uwsgi输出大量信息。
2、逻辑块空行分隔。
3、变量和其使用尽量放到一起。
4、【必须】 import过长，要放在多行的时候，
使用from xxx import（a, b, c）,不要用\换行。
5、Django Model定义的choices直接在定义在类里面。

2 前端编码规范

1、类的基础命名方式：项目英文简写-当前页-页面内容块
例如 .ijobs-index-box。

2、Id的基础命名方式：语义化，并使用下滑杠连接
例如，步骤名称可命名为#step_name
3、Javascript变量命名方式：
按照变量类型的首个字母为前缀，使用驼峰命名法；
例子：
var aName = ['lizi','zhaowu'];  //Array数组
var oBtn = window.document.getElementById('btn');  //Object对象
function fnName(){};  //Function函数
var nAge = 25;  //Integer(int)整型
var sWebURL="www.wyn.com";  //String字符串

3 日志规范

一、日志输出级别

1、Error：系统异常，影响用户使用，必须通知到开发者及时修复。
2、Warning：系统异常，不影响用户使用，但有异常需要跟进修复。
3、Info：系统流水日志或日常记录,不做通知配置。

二、日志输出格式

1、日志需要包含当前函数名，方便查找和定位。
2、重要操作流水直接记录数据库，可以保存较长时间。
3、错误日志要方便定位问题，建议记录当前参数以及上下文变量。

4 代码提交规范

每次代码提交必须有备注说明，注明本次提交做了哪些修改，commit 分类：

bugfix: -----线上功能bug
sprintfix: --未上线代码修改(功能模块未上线部分bug)
minor: ------不重要的修改(换行，拼写错误等)
feature: ----新功能说明

5 接口规范

Api的method：要根据实际请求的类型，查询一定要用 get，不能随意指定method。
一、接口返回内容

二、接口返回Status Code
充分利用HTTP Status Code作为响应结果的基本状态码，基本状态码不能区分的status。

三、接口数据验证
数据检验逻辑应当和业务逻辑分离，这样做的好处：
代码逻辑更加清晰。
数据校验逻辑可以复用。

分离方案：
1、form-data/url-params：Django-Form 
2、Json：Json-schema

6 代码注释

6.1 Python代码注释

一、方法注释
方法必须使用标注注释，如果是公有方法或对外提供的 API 相关方法，则最好给出使用样例。如：

二、Module注释
在开头要加入对该模块的注释。

三、普通代码注释
普通代码注释应该以‘#’和单个空格开始。
如果有需要调整或者需要优化的地方，可以使用#TODO这里是注释内容进行注释。

格式：'#'+单个空格+'TODO'+单个空格+注释内容。

6.2 前端代码注释

一、Html注释

<!-- 容器 -->
<div class=“container”>
...
<!-- 用户名 -->
<div id=“user_name”>
...
</div>
<!-- /用户名 -->
...
</div>
<!-- /容器 -->

二、css注释
内容比较少是可以只在顶部加注释，内容比较多时在尾部加结束标签/* 注释内容 end */。

/* 新建任务 start */
.new-task{}
/* 新建任务名 */
.task-name{color:#333;}
/* 新建任务时间 */
.task-created-time{background:url(img/clock.png) no-repeat;}
/* 新建任务 end */

三、Js注释
Js注释同上，函数如果有参数，建议简单备注一下参数的内容和类型。

7 文件或包的引用

一、Python代码
模块或包的引入最好使用完整路径，即使是同一个包下的相互引用，也建议使用完整路径。

这样比较方便代码阅读，同时若后续需修改为相对路径也很简单。

二、前端页面
在页面中引用css和js、或配置url路径时，必须使用“绝对路径”，而不要使用‘…/’，‘./’等相对路径的引用方式。

8 Python官方风格指南PEP8

PEP 8 是 Python Enhancement Proposal 的第 8 号提案，它详细规定了 Python 代码的风格要求，是 Python 社区公认的代码风格规范。

PEP 8 的一些规定：
使用 4 个空格缩进，不要使用制表符。
每行代码长度不超过 79 个字符，对于长的表达式应适当换行。
在运算符前后加上空格，但不要过度空格化。
使用全小写字母和下划线命名变量、函数和模块。
在函数之间空一行，类之间空两行，使代码结构更清晰。

8.1 规范代码自动化检查flake8

首先，安装 Flake8：
pip install flake8
然后，在命令行中运行 Flake8：
flake8 your_code.py

Flake8 会自动检查代码，指出不符合规范的地方，并给出建议。

8.2 规范代码自动化检查black

首先，安装 Black：
pip install black
然后，在命令行中运行 Black：
black your_code.py

Black 将自动格式化代码，并输出结果。建议慎用。