我们经常写代码，你的代码会写注释么？
如果你写代码不写注释，那并不是个好习惯，你可能会说，你的代码只会自己使用，而事实上，自己写的代码可能过段时间自己也会忘记当时要表达的含义。
而我们在日常做项目时，规范的注释是必不可少的。
例如我们经常写的Python，我们在学习Python时会学习到Python的注释分为两种单行注释和多行注释。
单行注释例如（右滑代码部分查看）：
stu_name = stu_info.get(stu_num) #从学生信息表中获取学生姓名
多行注释例如：
def check_info():
pass
"""
该函数的作用有如下几点：
1. xxx
2. xxx
"""
但是在实际项目中，仅仅这样的代码注释是不够的。
我们在写项目代码时，函数（或者方法）基本都会用到，一般针对函数我们都需要有文档字符串（可以理解为多行注释），当然如果函数对外部是不可见的，或者短小且容易理解，可以不加文档字符串。
函数的文档字符串应该包含函数的功能（函数做什么）、函数的输入和输出，目标是当别人调用该函数时，不需要看函数代码只看文档字符串即可使用。
当然，对于复杂的函数，除了文档字符串，在函数中的特定区域加入注释也十分重要，可以帮助理解局部的代码内容。
函数的注释常应该包含参数的信息，返回值的信息，异常相关信息，例如：
def check_info(stu_num,stu_info):
"""该函数的作用是通过学生信息字典，通过输入学生学号获取学生的姓名。
Arguments:
stu_num {str} -- 学生的学号
stu_info {dict} -- 学生信息字典
Returns:
None or str -- 学生姓名
"""
if stu_info == None:
return None
else:
stu_name = stu_info.get(stu_num)
if stu_name == None:
return ''
else:
return stu_name
Args描述了输入参数的类型和含义，Returns描述了输出值的类型和含义，有时还会使用Raises描述了异常信息。
我们常常会使用面向对象编程的方式来写项目代码，那么我们会用到类，类方法等等。
例如：
class Student(object):
def __init__(self):
self.stu_info = {}
def check_info(self, stu_num):
if self.stu_info == {}:
return ''
else:
stu_name = self.stu_info.get(stu_num)
if stu_name == None:
return ''
else:
return stu_name
但是接手你项目代码的人去了解你项目这段代码含义是略有困难的，所以不仅为了方便自己阅读代码，并且为了方便他人阅读代码，我们需要使用较为规范的注释方法。
例如我们将该段代码注释后的效果为：
class Student(object):
"""该学生类包含了学生的各种信息
"""
def __init__(self):
"""该初始化方法用于初始化学生信息
"""
self.stu_info = {}
def check_info(self, stu_num):
"""该方法的作用是通过学生信息字典，通过输入学生学号获取学生的姓名。
Arguments:
stu_num {str} -- 学生的学号
Returns:
str -- 学生姓名
"""
if self.stu_info == {}:
return ''
else:
stu_name = self.stu_info.get(stu_num)
if stu_name == None:
return ''
else:
return stu_name
在类的下面应该有一段文档字符串用于描述该类的含义和作用，并且如果类包含公共属性，我们需要在该段文档字符串中加入属性段的注释。
那我们如何快速的书写Python代码的文档字符串呢？我给大家推荐一个好的方法，因为本人使用VS Code来写Python项目代码，而VS Code中有个插件名为autoDocstring可以辅助我们写文档字符串。
我们如图操作VS Code，搜索出之后点击install安装：
安装成功后如图所示：
我们写个函数，然后回车之后输入三个英文双引号，按回车之后，我们会发现如下图所示：
然后我们在文档字符串模板上修改内容即可，是不是很方便呢？
其实，规范的代码管理流程中除了使用git相关的版本控制，还有代码审查 ，所以对于代码中较为复杂和技巧性的部分，可以加入块注释来说明。
所谓块注释，就是多个行注释组成。
我们一般将其加入在代码中较为复杂和技巧性的部分之前。
例如：
#以下部分的方法较为复杂
#通过xxx找到xxx，得到xxx
#最终实现xxx
def check_info(stu_num,stu_info):
pass
看完了本文，如果你的代码不够规范，赶紧规范起来吧，不管是正在写的代码还是以前写过的项目代码，翻出来看看还能看懂么？给他们加上完整规范的文档字符串吧~
欢迎关注我的公众号“数据科学杂谈”，原创技术文章第一时间推送。
