为了便于项目的管理和代码的阅读,养成良好的编码风格以及沟通方便,编码Python代码时应遵循以下编码规范:
- 每行长度不超过80个字符
每行代码的长度不超过80个字符
不要使用反斜杠( \ ) 连接行.Python会将圆括号,中括号和花括号中的行隐式连接起来,可以利用这个特点
例如,如果一个文本字符串在一行放不下,可以用圆括号来实现隐式行连接:
x = ('This will build a long long long long '
'long long long long string')
- 缩进使用4个空格缩进
统一用4个空格缩进代码,编辑器的文件编码格式统一设置为uft-8格式,如:
# -*- coding: utf-8 -*-
# 可以在编辑器中设置Tab的缩进和文件编码
- Shebang
程序的main文件和可执行脚本应该以如下方式开始:
#!/usr/bin/env python
#!/usr/bing/python2.7
注:在计算机科学中,Shebang是由一个井号和感叹号构成的字符串(#!),其出现在文本的第一行的前两个字符.在文本中存在Shebang的情况下,类Unix操作系统的程序载入器会分析shebang后的内容,将这些词作为解释器命令,并调用该指令,并将载有Shebang的文件路径作为该解释器的参数.
- 代码注释的使用
API,Model,function和class都需要写注释,代码的关键部分和难懂的逻辑以及补丁都需要有注释,良好易读的代码注释是编程的基本要求.
注释类型分为两种:文档注释用"""包围,行注释用#开头,后面空一格再写注释内容.
Function的注释建议如下:
def logic_get_client_basic_info(client_list, fields, from_third_party=False):
"""
Return a list of clients with basic information.
Args:
client_list: Client list, each element is a dict
fields: Information fields to be returned
from_third_party: If get basic info from third party open api. Note that
if set this True, it will slow down the return speed
Returns:
A list of clients, fill with company basic information
"""
names = list()
client_dict = dict()
for client in client_list:
names.append(client[Customer.ContactField.name])
client_dict[client[Customer.ContactField.name]] = client
enterprises = list(Enterprise.s_col.find(
{
Enterprise.Field.name: {'$in': names}
},
fields
))
found_names = list()
for enterprise in enterprises:
# 这里一定要使用 Enterprise 模型中的 name 字段替换搜索系统中的
# name 字段，因为同一个公司可能在搜索系统中有几个名字，但是只有
# 一个名字在 Enterprise 模型中存在
name = enterprise[Enterprise.Field.name]
found_names.append(name)
enterprise.pop('_id')
client_dict[name].update(enterprise)
if from_third_party:
# Check those names that not found
lack_names = [_ for _ in names if _ not in found_names]
ok, company_dict = logic_get_companies_by_fullname(lack_names)
if ok:
logic_update_into_enterprises(company_dict)
lack_enterprises = list(Enterprise.s_col.find(
{
Enterprise.Field.name: {'$in': names}
},
fields
))
for enterprise in lack_enterprises:
name = enterprise[Enterprise.Field.name]
enterprise.pop('_id')
client_dict[name].update(enterprise)
return [client_dict[_] for _ in names]
API或Model的注释用Markdown格式书写,方便调用脚本直接生成wiki,注释示例如下:
@api.route('/user', methods=['POST'])
def create_user():
"""
## Create User
Extra information to describe this api.
POST '/api/user'
Params:
* `username` (string) - User name
* `password` (string) - Md5 user password
* `signature` (string) *optional* - User signature
Returns:
* `_id` - New user id
Errors: `1001`, `1002`
---
"""
pass
- 导入模块
模块的导入按照系统自带模块,第三方模块和本项目模块的顺序导入,每种模块中间隔一个空行.每各种模块内根据模块的首字母按字典顺序排序.一行只能导入一个模块,若有多个需要导入,则用括号包围后换行.示例:
import os
import sys
from flask import (
jsonify,
request,
)
from logic.user import logic_get_user
from model.user import User
导入模块统一使用绝对路径.只导入需要的模块,应该避免
from . import xxx
from xxx.xxx import *
这种导入方式
- 命令规范
Python使用下划线命名法类名使用驼峰式命名方法,并且首字母大写.API接口的url使用短横线分割.所有常量使用大写+下划线表示法 - 术语
项目内的重要变量命名参照xxx项目术语表 - 对编写的代码运行pylint
pylint是一个在Python源代码中查找bug的工具,可以捕获容易忽视的错误,例如输入错误,使用未赋值的变量等.现在大部分Python代码编辑器中都有支持pylint - 时间的存储格式统一为utc datetime
存入数据库的时间统一为utc datetime格式,前端传参或者后台返回参数给前端均先转换为时间戳然后再返回.
