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

原文链接：https://www.jianshu.com/p/f5e5eebdd430

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