代码规范.注释
1.文档字符串存在于包,模块,类,函数中,通过__doc__提取,被pydoc所用,使用三重双引号(第一行是以句号/问号/惊叹号结尾的概述,第二行空行,下面剩下的部分应该与文档字符串的第一行的第一个引号对齐)
2.模块儿应该依次包含版权声明/许可样板/作者声明,标识文件的原作者
3.函数和方法,文档字符串中应该包含函数做什么,以及输入/输出的详细描述,生成器函数的文档字符串应该用"Yields"而非"Returns"
def yaml_detected(yaml_path):
"""Detected file is yaml format ?
Args:
yaml_path: Yaml file path
Returns:
Return a dict if with no error
example:
{'xmcloud': {'Rsync': {'rsync_dest': '....'},
'Script': {'act_restart': '....',
'act_start': '....',
'act_stop': '....'},
'web': {'Rsync': {'rsync_dest': '....'},
'Subversion': {'app_base': None,
'app_surl': None,
'svn_dest': '....',
'svn_pass': '....',
'svn_surl': '....',
'svn_user': '....',
'svn_vers': None}}}}
Raises:
IOError: [Errno 2] No such file or directory: yaml_path
"""
detected_res = None
try:
with open(yaml_path, 'r+b') as fhandle:
fd_yaml = fhandle.read()
detected_res = yaml.load(fd_yaml)
except IOError as Err:
Error = 'Found Error: %s' % (Err,)
sys.exit(Error)
return detected_res
4.类应该在其定义下有一个用于描述该类的文档字符串,类公共属性,那么文档中应该有一个属性段,并且应该遵循和函数参数相同的格式
class SvnChecker(object): """Check svn whether there is a new submission? Attributes: svn_ckey: svn base key svn_url: svn url address sta_timestamp: start timestamp end_timestamp: end timestamp """ def __init__(self, sta_timestamp, end_timestamp, svn_url, svn_ckey): self.svn_url = svn_url self.svn_ckey = svn_ckey self.sta_timestamp = sta_timestamp self.end_timestamp = end_timestamp def get_changed(self): """Get change of the svn commit from sta_timestamp to end_timestamp """
5.块注释和行注释,最需要写注释的是代码那些技巧性的部分,如果你在下次代码走查时必须解释一下,那么你应该现在就给它写注释,对于复杂的操作,应该在其操作开始前写上若干行注释,对于不是一目了然的代码,应该在其行尾添加注释,为了增加可读性,注释应该至少离开代码2个空格