Python代码规范笔记
2022/2/1 14:58:01
本文主要是介绍Python代码规范笔记,对大家解决编程问题具有一定的参考价值,需要的程序猿们随着小编来一起学习吧!
Python代码规范笔记
1. 代码格式
- 缩进 使用4个空格 - 行宽 每行不超过80个字符(特殊情况不超过120) 以下情况除外: 长的导入模块语句 注释里的URL(在注释中,如果必要,将长的URL放在一行上) - 引号 代码中多用单引号 自然语言使用双引号 正则表达式双引号 文旦注释三引号 - 空行 模块级函数和类定义之间空两行 类成员函数之间空一行 使用多个空行分隔多组相关的函数 函数中可以使用空行分隔逻辑相关代码 顶级定义之间空两行, 方法定义之间空一行 顶级定义之间空两行, 比如函数或者类定义. 方法定义, 类定义与第一个方法之间, 都应该空一行. 函数或方法中, 某些地方要是你觉得合适, 就空一行
class A: def __init__(self): pass def hello(self): pass def main(): pass
2. import语句
- 放在文件头部
# 分行书写 import os import sys from subprocess import Popen, PIPE # 使用absolute import from foo.bar import Bar # 按照顺序排列,每组之间用空行分隔 import os import sys import msgpack import zmq import foo # 导入其他模块的类定义可以使用相对导入 from myclass import MyClass # 命名冲突时使用命名空间 import bar import foo.bar bar.Bar() foo.bar.Bar()
3. 空格
- 代码各处不要有多余空格
# 二元运算符两边各空一格(=,-,+=,==,>,in,is not, and) i = i + 1 submitted += 1 x = x * 2 - 1 hypot2 = x * x + y * y c = (a + b) * (a - b) # 函数的参数列表中“,”之后要有空格 def complex(real, imag): pass # 函数的参数列表中,默认值等号两边不要添加空格 def complex(real, imag=0.0): pass
4. 换行
# 括号内的换行 # 第二行缩进到括号的起始处 foo = long_function_name(var_one, var_two, var_three, var_four) # 第二行缩进 4 个空格,适用于起始括号就换行的情形 def long_function_name( var_one, var_two, var_three, var_four): print(var_one) # 使用反斜杠\换行,二元运算符+` `.等应出现在行末;长字符串也可以用此法换行 session.query(MyTable).\ filter_by(id=1).\ one() print 'Hello, '\ '%s %s!' %\ ('Harry', 'Potter')
5. docstring
- 所有的公共模块、函数、类、方法,都应该写 docstring 。私有方法不一定需要,但应该在 def 后提供一个块注释来说明。
- docstring 的结束"""应该独占一行,除非此 docstring 只有一行。
"""Return a foobar Optional plotz says to frobnicate the bizbaz first. """ """Oneline docstring"""
6. 注释
- 块注释
“#”号后空一格,段落件用空行分开(同样需要“#”号)
# 块注释 # 块注释 # # 块注释 # 块注释
- 行注释
至少使用两个空格和语句分开,注意不要使用无意义的注释
x = x + 1 # 边框加粗一个像素
- 建议
在代码的关键部分(或比较复杂的地方), 能写注释的要尽量写注释
比较重要的注释段, 使用多个等号隔开, 可以更加醒目, 突出重要性
app = create_app(name, options) # ===================================== # 请勿在此处添加 get post等app路由行为 !!! # ===================================== if __name__ == '__main__': app.run()
- 文档注释(Docstring)
一般出现在模块头部、函数和类的头部,可以通过对象的__doc__对象获取文档,编辑器和IDE也可以根据Docstring给出自动提示
文档注释以 “”" 开头和结尾, 首行不换行, 如有多行, 末行必需换行, 以下是Google的docstring风格示例
# -*- coding: utf-8 -*- """Example docstrings. This module demonstrates documentation as specified by the `Google Python Style Guide`_. Docstrings may extend over multiple lines. Sections are created with a section header and a colon followed by a block of indented text. Example: Examples can be given using either the ``Example`` or ``Examples`` sections. Sections support any reStructuredText formatting, including literal blocks:: $ python example_google.py Section breaks are created by resuming unindented text. Section breaks are also implicitly created anytime a new section starts. """
具体描述其具体内容, 解释具体参数和返回值等
def function(a, b): """计算并返回a到b范围内数据的平均值""" ... ...
对函数参数、返回值等的说明采用numpy标准
def func(arg1, arg2): """在这里写函数的一句话总结(如: 计算平均值). 这里是具体描述. 参数 ---------- arg1 : int arg1的具体描述 arg2 : int arg2的具体描述 返回值 ------- int 返回值的具体描述 参看 -------- otherfunc : 其它关联函数等... 示例 -------- 示例使用doctest格式, 在`>>>`后的代码可以被文档测试工具作为测试用例自动运行 >>> a=[1,2,3] >>> print [x + 3 for x in a] [4, 5, 6] """
文档注释不限于中英文, 但不要中英文混用
文档注释不是越长越好, 通常一两句话能把情况说清楚即可
模块、公有类、公有方法, 能写文档注释的, 应该尽量写文档注释
-
文档注释
首先是一行以句号, 问号或惊叹号结尾的概述(或者该文档字符串单纯只有一行). 接着是一个空行. 接着是文档字符串剩下的部分, 它应该与文档字符串的第一行的第一个引号对齐 -
模块
每个文件应该包含一个许可样板. 根据项目使用的许可 -
函数和方法
一个函数必须要有文档字符串, 除非它满足以下条件:
1. 外部不可见
2. 非常短小
3. 简单明了
文档字符串应该包含函数做什么, 以及输入和输出的详细描述. 通常, 不应该描述"怎么做", 除非是一些复杂的算法. 文档字符串应该提供足够的信息, 当别人编写代码调用该函数时, 他不需要看一行代码, 只要看文档字符串就可以了. 对于复杂的代码, 在代码旁边加注释会比使用文档字符串更有意义.关于函数的几个方面应该在特定的小节中进行描述记录, 这几个方面如下文所述. 每节应该以一个标题行开始. 标题行以冒号结尾. 除标题行外, 节的其他内容应被缩进2个空格.
Args:
列出每个参数的名字, 并在名字后使用一个冒号和一个空格, 分隔对该参数的描述.如果描述太长超过了单行80字符,使用2或者4个空格的悬挂缩进(与文件其他部分保持一致). 描述应该包括所需的类型和含义. 如果一个函数接受foo(可变长度参数列表)或者**bar (任意关键字参数), 应该详细列出foo和**bar.
Returns: (或者 Yields: 用于生成器)
描述返回值的类型和语义. 如果函数返回None, 这一部分可以省略.
Raises:
列出与接口有关的所有异常.
def fetch_bigtable_rows(big_table, keys, other_silly_variable=None): """Fetches rows from a Bigtable. Retrieves rows pertaining to the given keys from the Table instance represented by big_table. Silly things may happen if other_silly_variable is not None. Args: big_table: An open Bigtable Table instance. keys: A sequence of strings representing the key of each table row to fetch. other_silly_variable: Another optional variable, that has a much longer name than the other args, and which does nothing. Returns: A dict mapping keys to the corresponding table row data fetched. Each row is represented as a tuple of strings. For example: {'Serak': ('Rigel VII', 'Preparer'), 'Zim': ('Irk', 'Invader'), 'Lrrr': ('Omicron Persei 8', 'Emperor')} If a key from the keys argument is missing from the dictionary, then that row was not found in the table. Raises: IOError: An error occurred accessing the bigtable.Table object. """ pass
- 类
类应该在其定义下有一个用于描述该类的文档字符串. 如果你的类有公共属性(Attributes), 那么文档中应该有一个属性(Attributes)段. 并且应该遵守和函数参数相同的格式.
class SampleClass(object): """Summary of class here. Longer class information.... Longer class information.... Attributes: likes_spam: A boolean indicating if we like SPAM or not. eggs: An integer count of the eggs we have laid. """ def __init__(self, likes_spam=False): """Inits SampleClass with blah.""" self.likes_spam = likes_spam self.eggs = 0 def public_method(self): """Performs operation blah."""
如果一个类不继承自其它类, 就显式的从object继承. 嵌套类也一样.
class SampleClass(object): pass class OuterClass(object): class InnerClass(object): pass class ChildClass(ParentClass): """Explicitly inherits from another class already."""
继承自 object 是为了使属性(properties)正常工作, 并且这样可以保护你的代码, 使其不受Python 3的一个特殊的潜在不兼容性影响. 这样做也定义了一些特殊的方法, 这些方法实现了对象的默认语义, 包括 new, init, delattr, getattribute, setattr, hash, repr, and str .
- TODO注释
为临时代码使用TODO注释, 它是一种短期解决方案. 不算完美, 但够好了.
TODO注释应该在所有开头处包含"TODO"字符串, 紧跟着是用括号括起来的你的名字, email地址或其它标识符. 然后是一个可选的冒号. 接着必须有一行注释, 解释要做什么. 主要目的是为了有一个统一的TODO格式, 这样添加注释的人就可以搜索到(并可以按需提供更多细节). 写了TODO注释并不保证写的人会亲自解决问题. 当你写了一个TODO, 请注上你的名字.
# TODO(kl@gmail.com): Use a "*" here for string repetition. # TODO(Zeke) Change this to use relations.
如果你的TODO是"将来做某事"的形式, 那么请确保你包含了一个指定的日期(“2009年11月解决”)或者一个特定的事件(“等到所有的客户都可以处理XML请求就移除这些代码”).
7. 命名规范
- 模块
模块尽量使用小写命名,首字母保持小写,尽量不要用下划线(除非多个单词,且数量不多的情况)
import decoder import html_parser
- 类名
类名使用驼峰(CamelCase)命名风格,首字母大写,私有类可用一个下划线开头
class Farm(): pass class AnimalFarm(Farm): pass class _PrivateFarm(Farm): pass
将相关的类和顶级函数放在同一个模块里
- 函数
函数名一律小写,如有多个单词,用下划线隔开
def run(): pass def run_with_env(): pass
私有函数在函数前加一个下划线_
class Person(): def _private_func(): pass
- 变量名
变量名尽量小写, 如有多个单词,用下划线隔开
if __name__ == '__main__': count = 0 school_name = ''
- 常量
常量采用全大写,如有多个单词,使用下划线隔开
MAX_CLIENT = 100 MAX_CONNECTION = 1000 CONNECTION_TIMEOUT = 600
这篇关于Python代码规范笔记的文章就介绍到这儿,希望我们推荐的文章对大家有所帮助,也希望大家多多支持为之网!
- 2024-11-01Python编程基础知识
- 2024-11-01Python编程基础
- 2024-10-31Python基础入门:理解变量与数据类型
- 2024-10-30Python股票自动化交易资料详解与实战指南
- 2024-10-30Python入行:新手必读的Python编程入门指南
- 2024-10-30Python入行:初学者必备的编程指南
- 2024-10-30Python编程入门指南
- 2024-10-30Python量化交易学习:新手入门指南
- 2024-10-30Python股票自动化交易实战入门教程
- 2024-10-29Python股票自动化交易教程:新手入门指南