![机械工程师Python编程:入门、实战与进阶](https://wfqqreader-1252317822.image.myqcloud.com/cover/439/51753439/b_51753439.jpg)
上QQ阅读APP看本书,新人免费读10天
设备和账号都新为新人
1.4 用文档字符串注释代码
当我们编写的代码可能被其他开发人员使用时,添加注释是一个好习惯。注释应该包括如何使用代码、代码使用的前提条件,以及每个函数的作用。
Python使用文档字符串(docstring)来注释代码。这些字符串用三引号(""")定义,是其注释的函数、类或模块的第一条语句。
你可能已经注意到,之前下载的Mechanics项目代码是使用这些文档字符串的方式。例如,matrix.py文件中Matrix类的方法被注释如下:
![](https://epubservercos.yuewen.com/AE06E7/30549606304263306/epubprivate/OEBPS/Images/37_01.jpg?sign=1734614915-PQakVkuCtpFq5QcMQpTiPzl6jvWtKWOm-0-776ac886c49778cd751b94c7a70e6b15)
如果在使用某段代码时,你有一些疑问,则可以使用Python全局函数help。对模块、函数、类或方法使用help函数,会返回对应代码的文档字符串。例如,我们可以在Python解释器控制台中获得set_data方法的注释文件,命令如下:
![](https://epubservercos.yuewen.com/AE06E7/30549606304263306/epubprivate/OEBPS/Images/37_02.jpg?sign=1734614915-qUyEo1MqzzFkXkBZpLAYx7NbT0Gok5HZ-0-1e31d972fd52cd79c6fed52c8422709d)
![](https://epubservercos.yuewen.com/AE06E7/30549606304263306/epubprivate/OEBPS/Images/38_01.jpg?sign=1734614915-mvnIvzNbrFKVBsDu1r1WSuXRCCpRrXI3-0-d94d6adfb380e8e6f9a4bc55abf4e98f)
一些自动化工具,如Sphinx(https://www.sphinx-doc.org/),可以将项目中的文档字符串生成HTML、PDF或plaintext格式的文档。你可以将这些文档与代码一起发布,这样其他开发人员就可以很好地学习你所写的代码。
考虑到篇幅有限,我们在本书中不会写文档字符串,但是在你下载的代码中都有,你可以去那里查看。