知识卡片
文档内容约定不同于语法标准
语言识别docstring的位置,却不强制统一的正文标记格式。仍应采用项目明确的说明约定,交代行为、参数、结果和必要限制;PEP257也已提供非强制的通用约定。原书缺少统一格式的感受不能扩展为从无任何规范。
本节建议用文档字符串说明对象做什么,用#说明局部复杂表达式如何工作。这是帮助读者的写作选择,不是编译器强制的内容分类;准确性与真实契约比只满足形式更重要。
这张卡片看不懂?
这张卡片已通过人工审查,不再接受失败反馈。
已有反馈 · 0 条
还没有人提交反馈。
在整书笔记中的位置
- · 文档内容约定不同于语法标准
- · 回顾文档字符串
原书出处 · 2 处
- · 查看原书依据
文档字符串的结构没有标准。如果你想用,就别犹豫。 内置文档字符串 Python中的内置模块和对象都使用类似的技术,在dir返回的属性列表前后加上文档。例如,要查看内置模块的可读的说明时,可将其导入,并打印其__doc__字符串。 内置模块内的函数、类以及方法在其__doc__属性内也有附加的说明信息。 也可以通过文档字符串读取内置函数的说明。 可以用这种方式
- · 查看原书依据
功能性文档(你的对象做什么)使用文档字符串;针对更加微观的文档(令人费解的表达式是如何工作的)使用#注释。
参考来源
- 位置:《Python学习手册(原书第4版)》第15章《文档字符串:__doc__》(spine690;extracted/OReilly精品图书系列共21册(《Javascript权威指南》、《机器学习:实用案例解析》、《编写可读代码的艺术》、《算法精解》等)/_epub-src/text/part0661.html;u340-ch15-005)。
- 结论依据:原文在“文档字符串的结构没有标准”附近的定义、例子或代码支撑本卡核心说明:语言识别docstring的位置,却不强制统一的正文标记格式。边界按已读前提解释;示例未执行。
- 原始内容:文档字符串的结构没有标准。如果你想用,就别犹豫。 内置文档字符串 Python中的内置模块和对象都使用类似的技术,在dir返回的属性列表前后加上文档。例如,要查看内置模块的可读的说明时,可将其导入,并打印其__doc__字符串。 内置模块内的函数、类以及方法在其__doc__属性内也有附加的说明信息。 也可以通过文档字符串读取内置函数的说明。 可以用这种方式
- 位置:《Python学习手册(原书第4版)》第28章《回顾文档字符串》(spine917;extracted/OReilly精品图书系列共21册(《Javascript权威指南》、《机器学习:实用案例解析》、《编写可读代码的艺术》、《算法精解》等)/_epub-src/text/part0888.html;u630-ch15-005)。
- 结论依据:本节建议用文档字符串说明对象做什么,用#说明局部复杂表达式如何工作。这是帮助读者的写作选择,不是编译器强制的内容分类;准确性与真实契约比只满足形式更重要。
- 原始内容:功能性文档(你的对象做什么)使用文档字符串;针对更加微观的文档(令人费解的表达式是如何工作的)使用#注释。