V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
推荐学习书目
Learn Python the Hard Way
Python Sites
PyPI - Python Package Index
http://diveintopython.org/toc/index.html
Pocoo
值得关注的项目
PyPy
Celery
Jinja2
Read the Docs
gevent
pyenv
virtualenv
Stackless Python
Beautiful Soup
结巴中文分词
Green Unicorn
Sentry
Shovel
Pyflakes
pytest
Python 编程
pep8 Checker
Styles
PEP 8
Google Python Style Guide
Code Style from The Hitchhiker's Guide
SimbaPeng
V2EX  ›  Python

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

  •  
  •   SimbaPeng · 2017-09-19 22:45:57 +08:00 · 5898 次点击
    这是一个创建于 2633 天前的主题,其中的信息可能已经有所发展或是发生改变。
    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 的注释却是使用大量文字来解释,而且没有一个规定的排版。这是为什么?
    24 条回复    2017-09-22 19:59:15 +08:00
    NoAnyLove
        1
    NoAnyLove  
       2017-09-19 22:48:49 +08:00
    没说不可以啊,如果你使用 doxygen 作为文档工具,当然可以按照 doxygen 的文档风格来写啊。至于你前面的 docstring 的写法只不过是官方 PEP 推荐的做法, 并没有强制要求。至于官方为什么推荐这种做法,大概是因为,Python 写代码就很像是在写句子吧
    6IbA2bj5ip3tK49j
        2
    6IbA2bj5ip3tK49j  
       2017-09-19 23:17:16 +08:00 via Android
    这不就是 java doc 吗。
    clino
        3
    clino  
       2017-09-19 23:28:49 +08:00 via Android   ❤️ 2
    “一眼就看出参数类型,返回值类型”
    然而我大 py 并不太 care 类型。。。
    rebeccaMyKid
        4
    rebeccaMyKid  
       2017-09-19 23:40:42 +08:00 via Android
    @clino h 哈哈哈哈
    halfcoder
        5
    halfcoder  
       2017-09-19 23:46:49 +08:00
    @clino #3
    ' '.join(["1", 1, 1.0]),请
    wangxn
        6
    wangxn  
       2017-09-20 00:18:00 +08:00 via Android
    Python 出现的时候,Doxygen 还不知道在哪里呢。
    wangxn
        7
    wangxn  
       2017-09-20 00:18:33 +08:00 via Android
    楼主的问题就像是中国人为什么不用英语一样。
    SimbaPeng
        8
    SimbaPeng  
    OP
       2017-09-20 02:51:01 +08:00   ❤️ 4
    @wangxn Python 出现的时候, utf-8 也不知道在哪里呢。那为什么现在 Python3 的默认编码使用 utf-8?

    你的回答就像我出生的时候还没有支付宝呢,我为什么要用它一样. 神逻辑。。。
    wwqgtxx
        9
    wwqgtxx  
       2017-09-20 07:32:09 +08:00 via iPhone
    就像 pypi 到现在都不支持.md 的说明文件,只支持.rst 我能说啥…
    xdqi
        10
    xdqi  
       2017-09-20 08:19:00 +08:00
    @halfcoder #5 这时候就需要 PEP 484 了
    mooncakejs
        11
    mooncakejs  
       2017-09-20 08:22:16 +08:00 via iPhone
    Python 从头到脚透露着一种与众不同的感觉
    justou
        12
    justou  
       2017-09-20 08:29:19 +08:00
    siteshen
        13
    siteshen  
       2017-09-20 09:12:59 +08:00   ❤️ 1
    为什么不用?因为各大语言基本有各自的文档规范。清晰明了是一方面,是否易维护也是需要考虑的因素。

    比如 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
        14
    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
        15
    wangxn  
       2017-09-20 11:11:05 +08:00 via Android
    Python 选择这种注释方式本就是历史的自然选择,不知道有什么好奇怪的。
    SimbaPeng
        16
    SimbaPeng  
    OP
       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,呵呵
    est
        17
    est  
       2017-09-20 11:23:00 +08:00
    @SimbaPeng 这是你跟 sys 做 IO 的默认编码。python 内部是 ucs2/ucs4 的编码。py3k 是智能编码(插入一个 emoji 字符串瞬间肥胖成 4 字节)。这些都不是 UTF-8


    @halfcoder 这个会抛异常。
    Gakho
        18
    Gakho  
       2017-09-20 11:28:16 +08:00
    @SimbaPeng 你这是搞混了吧? 流畅的 Python 第四章有介绍
    PythonAnswer
        19
    PythonAnswer  
       2017-09-20 13:43:48 +08:00 via iPad
    sys 库 老兄还没弄明白
    ioth
        20
    ioth  
       2017-09-20 14:15:03 +08:00
    注释能说明什么呢?
    大段的格式化语言,java 类就是培养懒人
    不喜欢看别人的东西,就想着别人要看你的东西
    NathanHu
        21
    NathanHu  
       2017-09-20 18:42:22 +08:00 via iPhone
    不同语言有不同注释,习惯就好,就算你知道了为什么也无法改变它,只能适应它。
    srlp
        22
    srlp  
       2017-09-22 19:54:34 +08:00
    楼主这是引战啊,明显是历史原因嘛。

    另外,你想要的格式也是有的,numpy doc format:
    srlp
        24
    srlp  
       2017-09-22 19:59:15 +08:00
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   3650 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 26ms · UTC 04:20 · PVG 12:20 · LAX 20:20 · JFK 23:20
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.