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 的注释却是使用大量文字来解释,而且没有一个规定的排版。这是为什么?
Python 为什么不用 doxygen 这种清晰明了的注释风格?
没说不可以啊,如果你使用 doxygen 作为文档工具,当然可以按照 doxygen 的文档风格来写啊。至于你前面的 docstring 的写法只不过是官方 PEP 推荐的做法, 并没有强制要求。至于官方为什么推荐这种做法,大概是因为,Python 写代码就很像是在写句子吧
Python社区有自己的文档风格约定,主要是PEP 257和docstring。Doxygen虽然清晰,但它是为C++/Java设计的,语法和Python的简洁哲学不太搭。Python用reStructuredText或Google/Numpy风格,配合Sphinx生成文档,这样更符合语言习惯,工具链也更成熟。
简单说,Python有自己的“方言”,用起来更顺手。
这不就是 java doc 吗。
“一眼就看出参数类型,返回值类型”
然而我大 py 并不太 care 类型。。。
h 哈哈哈哈
#3
’ '.join([“1”, 1, 1.0]),请
Python 出现的时候,Doxygen 还不知道在哪里呢。
楼主的问题就像是中国人为什么不用英语一样。
Python 出现的时候, utf-8 也不知道在哪里呢。那为什么现在 Python3 的默认编码使用 utf-8?
你的回答就像我出生的时候还没有支付宝呢,我为什么要用它一样. 神逻辑。。。
就像 pypi 到现在都不支持.md 的说明文件,只支持.rst 我能说啥…
#5 这时候就需要 PEP 484 了
Python 从头到脚透露着一种与众不同的感觉
为什么不用?因为各大语言基本有各自的文档规范。清晰明了是一方面,是否易维护也是需要考虑的因素。
比如 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 生成文档”。
谁说 Python 默认用 UTF-8 的? Python 用的是 Unicode。
CPython 内部用的是 C/C++的 wchar_t 数据类型,和 UTF-8 没有任何关系。
Python 选择这种注释方式本就是历史的自然选择,不知道有什么好奇怪的。
❯ 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,呵呵
这是你跟 sys 做 IO 的默认编码。python 内部是 ucs2/ucs4 的编码。py3k 是智能编码(插入一个 emoji 字符串瞬间肥胖成 4 字节)。这些都不是 UTF-8
这个会抛异常。
你这是搞混了吧? 流畅的 Python 第四章有介绍
sys 库 老兄还没弄明白
注释能说明什么呢?
大段的格式化语言,java 类就是培养懒人
不喜欢看别人的东西,就想着别人要看你的东西
不同语言有不同注释,习惯就好,就算你知道了为什么也无法改变它,只能适应它。
楼主这是引战啊,明显是历史原因嘛。
另外,你想要的格式也是有的,numpy doc format:

