给自己的Python代码写注释

204 阅读2分钟

写Python应用有很多年了,当拿起代码,或者由于程序要增加新的功能,又或者程序中有要修改的问题,我面对自己的代码会很清晰地找到要修改的地方太难了。每次都自己写的代码要费好长的时间来理清思路。

解决这样问题的方法,除了代码本身的功能的封装和解耦,另外的一个方法就是写好代码注释。

Python之父说过,“代码更多地是用来读的而不是用来写”。

如何为Python代码写文档呢? 我们先区分下注释和文档。

通常,注释是给开发者描述你的代码,主要面向代码的开发者或维护者。配合着写的好的代码,注释有助于读者更好的理解你的代码和代码的目的和设计。

代码文档是给用户描述代码的使用和功能。代码文档是面向用户或者代码的使用者。

先说下如何以及什么时候为代码写注释。

注释是以#开头的语句,注释的用途包括下面几个场景:

  1. 计划和审查 当你在开发新的代码功能时, 可以使用注释把代码的大纲和计划书写出来,在实际的代码实现完,评审和测试完,记住删除这些注释。
  2. 代码描述: 用于解释特定部分代码的目的
  3. 算法描述: 特别是复制的算法,注释解释算法如何工作,怎样实现,以及为什么选择该算法而非另外其他的。

PYthon3.5之后类型提示是另外的形式来帮助阅读代码快速了解函数的输入和输出类型。 再看一下Docstrings,使用三引号来进行文档化,进一步分为三个主要类别。

  1. class文档
  2. package 和module 文档
  3. script 脚本和函数文档

class docstrings 应该包含下面信息 class代码的目的和行为的概括 公共方法和简要描述 类的属性 和子类接口相关的信息 Documenting Python Code: A Complete Guide – Real Python

Python Docstrings Tutorial : Examples & Format for Pydoc, Numpy, Sphinx Doc Strings | DataCamp

可以参考的项目 Django Requests Click Pandas