Python 为什么不用 doxygen 这种清晰明了的注释风格？

python 的注释:
def round(number, ndigits=None): # real signature unknown; restored from __doc__
"""
round(number[, ndigits]) -> number

Round a number to a given precision in decimal digits (default 0 digits).
This returns an int when called with one argument, otherwise the
same type as the number. ndigits may be negative.
"""
return 0

doxygen:
/**
* Checks if value is a member of the set stored at the key key.
*
* @param string $key
* @param string $value
* @return bool TRUE if value is a member of the set at key key, FALSE otherwise.
* @link http://redis.io/commands/sismember
* @example
* <pre>
* $redis->sAdd('key1' , 'set1');
* $redis->sAdd('key1' , 'set2');
* $redis->sAdd('key1' , 'set3'); // 'key1' => {'set1', 'set2', 'set3'}
*
* $redis->sIsMember('key1', 'set1'); // TRUE
* $redis->sIsMember('key1', 'setX'); // FALSE
* </pre>
*/

我感觉 doxygen 的注释风格非常清晰明了，一眼就看出参数类型，返回值类型。而 python 的注释却是使用大量文字来解释，而且没有一个规定的排版。这是为什么？

key1'

redis-

number

key

24 条回复 • 2017-09-22 19:59:15 +08:00

NoAnyLove

2017-09-19 22:48:49 +08:00

没说不可以啊，如果你使用 doxygen 作为文档工具，当然可以按照 doxygen 的文档风格来写啊。至于你前面的 docstring 的写法只不过是官方 PEP 推荐的做法，并没有强制要求。至于官方为什么推荐这种做法，大概是因为，Python 写代码就很像是在写句子吧

6IbA2bj5ip3tK49j

2017-09-19 23:17:16 +08:00 via Android

这不就是 java doc 吗。

clino

2017-09-19 23:28:49 +08:00 via Android

“一眼就看出参数类型，返回值类型”
然而我大 py 并不太 care 类型。。。

rebeccaMyKid

2017-09-19 23:40:42 +08:00 via Android

@clino h 哈哈哈哈

halfcoder

2017-09-19 23:46:49 +08:00

@clino #3
' '.join(["1", 1, 1.0])，请

wangxn

2017-09-20 00:18:00 +08:00 via Android

Python 出现的时候，Doxygen 还不知道在哪里呢。

wangxn

2017-09-20 00:18:33 +08:00 via Android

楼主的问题就像是中国人为什么不用英语一样。

SimbaPeng

2017-09-20 02:51:01 +08:00

@wangxn Python 出现的时候, utf-8 也不知道在哪里呢。那为什么现在 Python3 的默认编码使用 utf-8?

你的回答就像我出生的时候还没有支付宝呢，我为什么要用它一样. 神逻辑。。。

wwqgtxx

2017-09-20 07:32:09 +08:00 via iPhone

就像 pypi 到现在都不支持.md 的说明文件，只支持.rst 我能说啥…

xdqi

2017-09-20 08:19:00 +08:00

@halfcoder #5 这时候就需要 PEP 484 了

mooncakejs

2017-09-20 08:22:16 +08:00 via iPhone

Python 从头到脚透露着一种与众不同的感觉

justou

2017-09-20 08:29:19 +08:00

就是因为没有显式的类型声明, python 才越来越重视变量类型的吧
https://www.python.org/dev/peps/pep-0484/
https://www.python.org/dev/peps/pep-3107/#use-cases
https://stackoverflow.com/questions/3038033/what-are-good-uses-for-python3s-function-annotations

siteshen

2017-09-20 09:12:59 +08:00

为什么不用？因为各大语言基本有各自的文档规范。清晰明了是一方面，是否易维护也是需要考虑的因素。

比如 python 有定义自己的文档规范 https://www.python.org/dev/peps/pep-0257/ 和标记语言 http://docutils.sourceforge.net/ 。
初步了解 doxygen 最初是为写 C/C++ 文档用的，和其他 java doc, javascript doc 之类的一样，都想从给一门语言加注释文档出发直到一统天下，不过谁也不服谁。
这些文档风格对本语言的支持都很不错，但不一定特别适合其他语言。静态、动态类型之分，强、弱类型语言，可能对文档的需求都不太一样。
常年使用某语言的人，文档也会跟着某语言社区的风格走，社区文化导致的，除非特别适用，否则很难该换风格。

相应地，也可以问“ C/C++为什么不用 rst 写文档”，“ javascript 为什么很少用 doxygen 生成文档”。

wangxn

2017-09-20 11:04:47 +08:00 via Android

@SimbaPeng 谁说 Python 默认用 UTF-8 的？ Python 用的是 Unicode。
CPython 内部用的是 C/C++的 wchar_t 数据类型，和 UTF-8 没有任何关系。

wangxn

2017-09-20 11:11:05 +08:00 via Android

Python 选择这种注释方式本就是历史的自然选择，不知道有什么好奇怪的。

SimbaPeng

2017-09-20 11:20:07 +08:00

@wangxn
❯ python3
Python 3.6.2 (default, Jul 17 2017, 16:44:47)
[GCC 4.2.1 Compatible Apple LLVM 8.0.0 (clang-800.0.42.1)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.getdefaultencoding()
'utf-8'

❯ python2
Python 2.7.13 (default, Jul 18 2017, 09:16:53)
[GCC 4.2.1 Compatible Apple LLVM 8.0.0 (clang-800.0.42.1)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.getdefaultencoding()
'ascii'
>>>

历史还选择了 ascii，呵呵