python编码规范(四)--注释，文档

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 <[e-mail]># Portions Copyright (C) 2009 David Jones <[e-mail]># And probably portions Copyright (C) 2006 Nicko van Someren <[e-mail]>## 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.htmlfrom __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): 进程号   
    """

作者：Godric_wsw
链接：https://www.jianshu.com/p/f5e5eebdd430