python编码规范(四)--注释，文档-优快云博客

本文详细介绍了Python脚本中注释的规范，包括块注释、行内注释和非公共方法注释的使用方式，以及如何撰写文档说明，适用于公共模块、公共类和公共方法。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

1.注释

块注释
块注释内部的段落通常只用一个#作为空行的分隔

#!/usr/bin/env python
# -*- coding:utf-8 -*-
# title           :backup_full.py
# description     :MySQL全量备份
# author          :w.s.w
# date            :20180601
# version         :1.0
# notes           :
# python_version  :2.7
#==============================================================================

行内注释
井前至少使用两个空格和代码语句分开，#后面有单个空格，注意避免使用无意义的注释

x = x + 1                 # 行内注释

非公共方法注释
非公共的方法没有必要写文档说明，但是应该有一个描述方法具体作用的注释，这个注释应该在def那一行之后

def backup_synth(args):
    # 增量备份
    logger.info('backup_synth')

2.文档说明

公共模块
写在块注释后，import前

#!/usr/bin/env python

# png.py - PNG encoder/decoder in pure Python
#
# Copyright (C) 2006 Johann C. Rocholl <johann@browsershots.org>
# Portions Copyright (C) 2009 David Jones <drj@pobox.com>
# And probably portions Copyright (C) 2006 Nicko van Someren <nicko@nicko.org>
#
# Original concept by Johann C. Rocholl.
#
# LICENCE (MIT)



"""
Pure Python PNG Reader/Writer


And now, my famous members
--------------------------
"""

# http://www.python.org/doc/2.2.3/whatsnew/node5.html
from __future__ import generators

__version__ = "0.0.18"

from array import array

公共类，公共方法
写在def, class后，取一层缩进

def backup_alone(self, args):  
    """单通道备份函数
    Parameters:
        filesystem(str): 文件系统
        mountpoint(str): 挂载点
        include(str): 包含文件
        exclude(str): 排除文件
    Returns:
        pid(str): 进程号   
    """