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

[SimbaPeng]

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 的注释却是使用大量文字来解释，而且没有一个规定的排版。这是为什么？

[NoAnyLove]

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

[6IbA2bj5ip3tK49j]

这不就是 java doc 吗。

[clino]

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

[rebeccaMyKid]

@clino h 哈哈哈哈

[halfcoder]

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

[wangxn]

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

[wangxn]

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

[SimbaPeng]

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

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

[wwqgtxx]

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

[xdqi]

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

[mooncakejs]

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

[justou]

就是因为没有显式的类型声明, 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]

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

比如 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]

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

[wangxn]

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

[SimbaPeng]

@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，呵呵

[est]

@SimbaPeng 这是你跟 sys 做 IO 的默认编码。python 内部是 ucs2/ucs4 的编码。py3k 是智能编码（插入一个 emoji 字符串瞬间肥胖成 4 字节）。这些都不是 UTF-8


@halfcoder 这个会抛异常。

[Gakho]

@SimbaPeng 你这是搞混了吧? 流畅的 Python 第四章有介绍

[PythonAnswer]

sys 库 老兄还没弄明白

[ioth]

注释能说明什么呢？
大段的格式化语言，java 类就是培养懒人
不喜欢看别人的东西，就想着别人要看你的东西