1
no1xsyzy 2019-03-11 14:44:25 +08:00
不是 “ docstring 只能拿来写类型标注”
而是 “只能拿 docstring 来写类型标注” |
2
kuangwinnie OP @no1xsyzy https://www.python.org/dev/peps/pep-0257/
我的理解是 docstring 除了写 doc 就不应该用了 是不能用来写 comment 的 docstring <-> doc |
3
ungrown 2019-03-13 15:42:17 +08:00 via Android 1
类型标注、docstring、注释,这是三样东西。
pep484 在老版本中不支持,而且本身还是实验性质。 docstring 在任何情况下都可以作为说明文档,除了标注以外,还可以写任何你想写的内容,这里面分行也不需要'\n'。 Python 没有专门的块注释、多行注释,因为 Python 的注释就是个井号开头的行,你想写几行注释就写几行。 注释是井号开头的一行文字,三重引号不是注释而是 docstring,docstring 里分行不需要'\n'这样的转义符号,只有字符串、字节串之类的对象才需要手工加换行符表示新行。 |
4
kuangwinnie OP @ungrown \n 只是个举例
|
5
ungrown 2019-03-14 13:46:48 +08:00 via Android
我是个菜鸟,我假设你是个老鸟,有些结论和经验你应该比我清楚,就算不清楚等我说完你也能立刻理解。
Python 作为一种动态类型、强类型语言,本身就倡导鸭子类型的设计理念,并不需要把数据的类型和结构定地特别死,自然也没必要在文档中不厌其烦地说太多。 如果对象的类型和内部结构非常复杂,比如是个列表,里面装了 dict,dict 里面又嵌套 dict,而且某些 key 还得是专门的字符串。这样复杂的对象本来就不太可能用简单的类型标注说清楚,还是老老实实在 docstring 里码字才是正道。 如果对象类型足够简单,你甚至连 docstring 都不需要表明类型,直接在参量名称上加点后缀都能表达清楚。 如果复杂度介于上述两者之间,我觉得用 pep484 可能会非常省事,针对某些情况。 而现实中上述三种情况彻底混作一团,那自然是具体问题具体分析。但又考虑到这点小事没必要花太多精力非要选择一个最佳方案,再考虑到团队代码风格可能有硬性要求,就更没必要在类型标注的方法选择这个问题上过于纠结。 |
6
kuangwinnie OP |
7
no1xsyzy 2019-03-15 20:32:58 +08:00 1
@kuangwinnie docstring 仅限于一个块的第一个语句是字符串的情况。
在其他地方出现不是 docstring 例: https://pastebin.com/84AbtbtG (打完想起来这边 gist 能直接显示……) |