Python编程中的开发规范有哪些？
- 内容介绍
- 文章标签
- 相关推荐
本文共计2372个文字，预计阅读时间需要10分钟。
名称规范Python之命名规范TypePublicInternal Moduleslower_with_underPackageslower_with_underClassesCapWordsExceptionsCapWordsFunctionslower_with_under()()_lower_with_under()
命名规范
Python之父推荐的规范
Type
Public
Internal
Modules
lower_with_under
_lower_with_under
Packages
lower_with_under
Classes
CapWords
_CapWords
Exceptions
CapWords
Functions
lower_with_under()
_lower_with_under()
Global/Class Constants
CAPS_WITH_UNDER
_CAPS_WITH_UNDER
Global/Class Variables
lower_with_under
lower_with_under
Instance Variables
lower_with_under
_lower_with_under (protected) or __lower_with_under (private)
Method Names
lower_with_under()
_lower_with_under() (protected) or __lower_with_under() (private)
Function/Method Parameters
lower_with_under
Local Variables
lower_with_under
应该避免的名称
1.单字符名称2.包/模块名中使用连字符(-)而不使用下划线(_)
3.双下划线开头并结尾的名称（如__init__）
命名约定
1.所谓”内部(Internal)”表示仅模块内可用, 或者, 在类内是保护或私有的.2.用单下划线(_)开头表示模块变量或函数是protected的(使用import * from时不会包含).
3.用双下划线(__)开头的实例变量或方法表示类内私有.
4.将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块.
5.对类名使用大写字母开头的单词(如CapWords, 即Pascal风格), 但是模块名应该用小写加下划线的方式(如lower_with_under.py).
注释规范
文档字符串
Python使用文档字符串作为注释方式: 文档字符串是包, 模块, 类或函数里的第一个语句. 这些字符串可以通过对象的doc成员被自动提取, 并且被pydoc所用. 我们对文档字符串的惯例是使用三重双引号”“”( PEP-257 ).
一个文档字符串应该这样组织:
1. 首先是一行以句号, 问号或惊叹号结尾的概述(或者该文档字符串单纯只有一行). 接着是一个空行.
2. 接着是文档字符串剩下的部分, 它应该与文档字符串的第一行的第一个引号对齐.
Used to xxx a :class: `JsonResponse `, which is xxx
:param data: response data
:param file: response files
Usage::
>>> import api
>>> rep = api.Response(url="www.baidu.com")
"""
行内注释(PEP8)
行内注释是与代码语句同行的注释
1. 行内注释和代码至少要有两个空格分隔
2. 注释由#和一个空格开始
模块
每个文件应该包含一个许可样板. 根据项目使用的许可(例如, Apache 2.0, BSD, LGPL, GPL), 选择合适的样板.
# -*- coding: utf-8 -*-# (C) JiaaoCap, Inc. 2017-2018
# All rights reserved
# Licensed under Simplified BSD License (see LICENSE)
函数和方法
一个函数必须要有文档字符串, 除非它满足以下条件:
1. 外部不可见
2. 非常短小
3. 简单明了
文档字符串应该包含函数做什么, 以及输入和输出的详细描述
文档字符串应该提供足够的信息, 当别人编写代码调用该函数时, 他不需要看一行代码, 只要看文档字符串就可以了
对于复杂的代码, 在代码旁边加注释会比使用文档字符串更有意义.
"""Constructs and sends a :class:`Request `.
:param method: method for the new :class:`Request` object.
:param timeout: (optional) How many seconds to wait for the server to send data
before giving up, as a float, or a :ref:`(connect timeout, read
timeout) ` tuple.
:type timeout: float or tuple
:return: :class:`Response ` object
:rtype: requests.Response
Usage::
>>> import requests
>>> req = requests.request('GET', '', a)
"""
def __init__(self, pool_connections, max_retries):
self.pool_connections = pool_connections
self.max_retries = max_retries
块注释和行注释
对于复杂的操作, 应该在其操作开始前写上若干行注释. 对于不是一目了然的代码, 应在其行尾添加注释.
# We use a weighted dictionary search to find out where i is in# the array. We extrapolate position based on the largest num
# in the array and the array size and then do binary search to
# get the exact number.
if i & (i-1) == 0: # true iff i is a power of 2
行长度
query_sql = "SELECT image_id, image_o, image_width, image_height "\
"FROM active_image_tbl "\
"WHERE auction_id=:auction_id AND status=1 " \
"ORDER BY image_id DESC"
YES:
agent_sql = ("CREATE TABLE IF NOT EXISTS db_agent ("
"id INTEGER PRIMARY KEY AUTOINCREMENT, "
"device_id VARCHAR(128) DEFAULT '', "
"status INTEGER DEFAULT 1, "
"updated_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP, "
"created_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP)")
在注释中，如果必要，将长的URL放在一行上。
Yes:
# See details at
# www.example.com/us/developer/documentation/api/content/v2.0/fication.html
换行
foo = long_function_name(var_one, var_two,
var_three, var_four)
# 4空格的悬挂式缩进(这时第一行不应该有参数)
foo = long_function_name(
var_one, var_two, var_three,
var_four)
空格
spam(ham[1], {eggs: 2}, []) # 注意标点两边的空格
NO:
spam( ham[ 1 ], { eggs: 2 }, [ ] )
if x == 4:
print x, y
x, y = y, x
NO:
if x == 4 :
print x , y
x , y = y , x
return magic(r=real, i=imag)
foo = 1000 # comment
long_name = 2 # comment that should not be aligned
NO:
foo = 1000 # comment
long_name = 2 # comment that should not be aligned
模块导入
import os
import sys
from subprocess import Popen, PIPE # PEP8
NO:
import sys, os
from foo import bar
from foo.bar import baz
from foo.bar import Quux
from Foob import ar
TODO注释
# TODO(Zeke) Change this to use relations.
二元运算符换行(PEP8)
# 不推荐: 操作符离操作数太远income = (gross_wages +
taxable_interest +
(dividends - qualified_dividends) -
ira_deduction -
student_loan_interest)
# 推荐：运算符和操作数很容易进行匹配
income = (gross_wages
+ taxable_interest
+ (dividends - qualified_dividends)
- ira_deduction
- student_loan_interest)
其它规范
Pandas使用规范
目录结构示例
|--docs|--requests
| |--__init__.py
| |--_internal_utils.py
| |--utils.py
| |--api.py
|--tests
|--setup.py
|--README.rst
|--LICENSE
Class结构示例
# -*- coding: utf-8 -*-# (C) JiaaoCap, Inc. 2017-2018
# All rights reserved
# Licensed under Simplified BSD License (see LICENSE)
"""
requests.api
This module contains xxx.
This module is designed to xxx.
"""
# stdlib
import os
import time
from base64 import b64encode
# 3p
try:
import psutil
exception ImportError:
psutil = None
import simplejson as json
# project
from .utils import current_time
from ._internal_utils import internal_func
class Response(object):
"""A user-created :class:`Response ` object.
Used to xxx a :class: `JsonResponse `, which is xxx
:param data: response data
:param file: response files
Usage::
>>> import api
>>> rep = api.Response(url="www.baidu.com")
"""
def __init__(self, data, files, json, url)
self.data = data
@staticmethod
def _sort_params(params):
"""This is a private static method"""
return params
def to_json():
"""The fully method blala bian shen,
xxx sent to the server.
Usage::
>>> import api
>>> rep = api.Response(url="www.baidu.com")
>>> rep.to_json()
"""
if self.url == "www":
return True
return False
相关链接
- Google开源项目风格指南:zh-google-styleguide.readthedocs.io/en/latest/
- PEP 8 -- Style Guide for Python Code:www.python.org/dev/peps/pep-0008/
- Python PEP8 编码规范中文版
本文共计2372个文字，预计阅读时间需要10分钟。
名称规范Python之命名规范TypePublicInternal Moduleslower_with_underPackageslower_with_underClassesCapWordsExceptionsCapWordsFunctionslower_with_under()()_lower_with_under()
命名规范
Python之父推荐的规范
Type
Public
Internal
Modules
lower_with_under
_lower_with_under
Packages
lower_with_under
Classes
CapWords
_CapWords
Exceptions
CapWords
Functions
lower_with_under()
_lower_with_under()
Global/Class Constants
CAPS_WITH_UNDER
_CAPS_WITH_UNDER
Global/Class Variables
lower_with_under
lower_with_under
Instance Variables
lower_with_under
_lower_with_under (protected) or __lower_with_under (private)
Method Names
lower_with_under()
_lower_with_under() (protected) or __lower_with_under() (private)
Function/Method Parameters
lower_with_under
Local Variables
lower_with_under
应该避免的名称
1.单字符名称2.包/模块名中使用连字符(-)而不使用下划线(_)
3.双下划线开头并结尾的名称（如__init__）
命名约定
1.所谓”内部(Internal)”表示仅模块内可用, 或者, 在类内是保护或私有的.2.用单下划线(_)开头表示模块变量或函数是protected的(使用import * from时不会包含).
3.用双下划线(__)开头的实例变量或方法表示类内私有.
4.将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块.
5.对类名使用大写字母开头的单词(如CapWords, 即Pascal风格), 但是模块名应该用小写加下划线的方式(如lower_with_under.py).
注释规范
文档字符串
Python使用文档字符串作为注释方式: 文档字符串是包, 模块, 类或函数里的第一个语句. 这些字符串可以通过对象的doc成员被自动提取, 并且被pydoc所用. 我们对文档字符串的惯例是使用三重双引号”“”( PEP-257 ).
一个文档字符串应该这样组织:
1. 首先是一行以句号, 问号或惊叹号结尾的概述(或者该文档字符串单纯只有一行). 接着是一个空行.
2. 接着是文档字符串剩下的部分, 它应该与文档字符串的第一行的第一个引号对齐.
Used to xxx a :class: `JsonResponse `, which is xxx
:param data: response data
:param file: response files
Usage::
>>> import api
>>> rep = api.Response(url="www.baidu.com")
"""
行内注释(PEP8)
行内注释是与代码语句同行的注释
1. 行内注释和代码至少要有两个空格分隔
2. 注释由#和一个空格开始
模块
每个文件应该包含一个许可样板. 根据项目使用的许可(例如, Apache 2.0, BSD, LGPL, GPL), 选择合适的样板.
# -*- coding: utf-8 -*-# (C) JiaaoCap, Inc. 2017-2018
# All rights reserved
# Licensed under Simplified BSD License (see LICENSE)
函数和方法
一个函数必须要有文档字符串, 除非它满足以下条件:
1. 外部不可见
2. 非常短小
3. 简单明了
文档字符串应该包含函数做什么, 以及输入和输出的详细描述
文档字符串应该提供足够的信息, 当别人编写代码调用该函数时, 他不需要看一行代码, 只要看文档字符串就可以了
对于复杂的代码, 在代码旁边加注释会比使用文档字符串更有意义.
"""Constructs and sends a :class:`Request `.
:param method: method for the new :class:`Request` object.
:param timeout: (optional) How many seconds to wait for the server to send data
before giving up, as a float, or a :ref:`(connect timeout, read
timeout) ` tuple.
:type timeout: float or tuple
:return: :class:`Response ` object
:rtype: requests.Response
Usage::
>>> import requests
>>> req = requests.request('GET', '', a)
"""
def __init__(self, pool_connections, max_retries):
self.pool_connections = pool_connections
self.max_retries = max_retries
块注释和行注释
对于复杂的操作, 应该在其操作开始前写上若干行注释. 对于不是一目了然的代码, 应在其行尾添加注释.
# We use a weighted dictionary search to find out where i is in# the array. We extrapolate position based on the largest num
# in the array and the array size and then do binary search to
# get the exact number.
if i & (i-1) == 0: # true iff i is a power of 2
行长度
query_sql = "SELECT image_id, image_o, image_width, image_height "\
"FROM active_image_tbl "\
"WHERE auction_id=:auction_id AND status=1 " \
"ORDER BY image_id DESC"
YES:
agent_sql = ("CREATE TABLE IF NOT EXISTS db_agent ("
"id INTEGER PRIMARY KEY AUTOINCREMENT, "
"device_id VARCHAR(128) DEFAULT '', "
"status INTEGER DEFAULT 1, "
"updated_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP, "
"created_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP)")
在注释中，如果必要，将长的URL放在一行上。
Yes:
# See details at
# www.example.com/us/developer/documentation/api/content/v2.0/fication.html
换行
foo = long_function_name(var_one, var_two,
var_three, var_four)
# 4空格的悬挂式缩进(这时第一行不应该有参数)
foo = long_function_name(
var_one, var_two, var_three,
var_four)
空格
spam(ham[1], {eggs: 2}, []) # 注意标点两边的空格
NO:
spam( ham[ 1 ], { eggs: 2 }, [ ] )
if x == 4:
print x, y
x, y = y, x
NO:
if x == 4 :
print x , y
x , y = y , x
return magic(r=real, i=imag)
foo = 1000 # comment
long_name = 2 # comment that should not be aligned
NO:
foo = 1000 # comment
long_name = 2 # comment that should not be aligned
模块导入
import os
import sys
from subprocess import Popen, PIPE # PEP8
NO:
import sys, os
from foo import bar
from foo.bar import baz
from foo.bar import Quux
from Foob import ar
TODO注释
# TODO(Zeke) Change this to use relations.
二元运算符换行(PEP8)
# 不推荐: 操作符离操作数太远income = (gross_wages +
taxable_interest +
(dividends - qualified_dividends) -
ira_deduction -
student_loan_interest)
# 推荐：运算符和操作数很容易进行匹配
income = (gross_wages
+ taxable_interest
+ (dividends - qualified_dividends)
- ira_deduction
- student_loan_interest)
其它规范
Pandas使用规范
目录结构示例
|--docs|--requests
| |--__init__.py
| |--_internal_utils.py
| |--utils.py
| |--api.py
|--tests
|--setup.py
|--README.rst
|--LICENSE
Class结构示例
# -*- coding: utf-8 -*-# (C) JiaaoCap, Inc. 2017-2018
# All rights reserved
# Licensed under Simplified BSD License (see LICENSE)
"""
requests.api
This module contains xxx.
This module is designed to xxx.
"""
# stdlib
import os
import time
from base64 import b64encode
# 3p
try:
import psutil
exception ImportError:
psutil = None
import simplejson as json
# project
from .utils import current_time
from ._internal_utils import internal_func
class Response(object):
"""A user-created :class:`Response ` object.
Used to xxx a :class: `JsonResponse `, which is xxx
:param data: response data
:param file: response files
Usage::
>>> import api
>>> rep = api.Response(url="www.baidu.com")
"""
def __init__(self, data, files, json, url)
self.data = data
@staticmethod
def _sort_params(params):
"""This is a private static method"""
return params
def to_json():
"""The fully method blala bian shen,
xxx sent to the server.
Usage::
>>> import api
>>> rep = api.Response(url="www.baidu.com")
>>> rep.to_json()
"""
if self.url == "www":
return True
return False
相关链接
- Google开源项目风格指南:zh-google-styleguide.readthedocs.io/en/latest/
- PEP 8 -- Style Guide for Python Code:www.python.org/dev/peps/pep-0008/
- Python PEP8 编码规范中文版