Python风格规范

为了便于项目的管理和代码的阅读,养成良好的编码风格以及沟通方便,编码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格式,前端传参或者后台返回参数给前端均先转换为时间戳然后再返回.