python如何注释一段代码_你真的会写Python项目代码注释么？

我们经常写代码，你的代码会写注释么？

如果你写代码不写注释，那并不是个好习惯，你可能会说，你的代码只会自己使用，而事实上，自己写的代码可能过段时间自己也会忘记当时要表达的含义。

而我们在日常做项目时，规范的注释是必不可少的。

例如我们经常写的Python，我们在学习Python时会学习到Python的注释分为两种单行注释和多行注释。

单行注释例如（右滑代码部分查看）：stu_name = stu_info.get(stu_num) #从学生信息表中获取学生姓名

多行注释例如：def check_info():pass"""该函数的作用有如下几点：1. xxx2. xxx"""

但是在实际项目中，仅仅这样的代码注释是不够的。

我们在写项目代码时，函数（或者方法）基本都会用到，一般针对函数我们都需要有文档字符串（可以理解为多行注释），当然如果函数对外部是不可见的，或者短小且容易理解，可以不加文档字符串。

函数的文档字符串应该包含函数的功能（函数做什么）、函数的输入和输出，目标是当别人调用该函数时，不需要看函数代码只看文档字符串即可使用。

当然，对于复杂的函数，除了文档字符串，在函数中的特定区域加入注释也十分重要，可以帮助理解局部的代码内容。

函数的注释常应该包含参数的信息，返回值的信息，异常相关信息，例如：def check_info(stu_num,stu_info):"""该函数的作用是通过学生信息字典，通过输入学生学号获取学生的姓名。Arguments: stu_num {str} -- 学生的学号 stu_info {dict} -- 学生信息字典 Returns: None or str -- 学生姓名 """if stu_info == None:return Noneelse: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#最终实现xxxdef check_info(stu_num,stu_info):pass

看完了本文，如果你的代码不够规范，赶紧规范起来吧，不管是正在写的代码还是以前写过的项目代码，翻出来看看还能看懂么？给他们加上完整规范的文档字符串吧~

欢迎关注我的公众号“数据科学杂谈”，原创技术文章第一时间推送。