Python 为什么不用 doxygen 这种清晰明了的注释风格? - V2EX
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 6338 次点击
    这是一个创建于 2951 天前的主题,其中的信息可能已经有所发展或是发生改变。
    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     Solana     2533 人在线   最高记录 6679       Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 26ms UTC 06:29 PVG 14:29 LAX 23:29 JFK 02:29
    Do have faith in what you're doing.
    ubao msn snddm index pchome yahoo rakuten mypaper meadowduck bidyahoo youbao zxmzxm asda bnvcg cvbfg dfscv mmhjk xxddc yybgb zznbn ccubao uaitu acv GXCV ET GDG YH FG BCVB FJFH CBRE CBC GDG ET54 WRWR RWER WREW WRWER RWER SDG EW SF DSFSF fbbs ubao fhd dfg ewr dg df ewwr ewwr et ruyut utut dfg fgd gdfgt etg dfgt dfgd ert4 gd fgg wr 235 wer3 we vsdf sdf gdf ert xcv sdf rwer hfd dfg cvb rwf afb dfh jgh bmn lgh rty gfds cxv xcv xcs vdas fdf fgd cv sdf tert sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf shasha9178 shasha9178 shasha9178 shasha9178 shasha9178 liflif2 liflif2 liflif2 liflif2 liflif2 liblib3 liblib3 liblib3 liblib3 liblib3 zhazha444 zhazha444 zhazha444 zhazha444 zhazha444 dende5 dende denden denden2 denden21 fenfen9 fenf619 fen619 fenfe9 fe619 sdf sdf sdf sdf sdf zhazh90 zhazh0 zhaa50 zha90 zh590 zho zhoz zhozh zhozho zhozho2 lislis lls95 lili95 lils5 liss9 sdf0ty987 sdft876 sdft9876 sdf09876 sd0t9876 sdf0ty98 sdf0976 sdf0ty986 sdf0ty96 sdf0t76 sdf0876 df0ty98 sf0t876 sd0ty76 sdy76 sdf76 sdf0t76 sdf0ty9 sdf0ty98 sdf0ty987 sdf0ty98 sdf6676 sdf876 sd876 sd876 sdf6 sdf6 sdf9876 sdf0t sdf06 sdf0ty9776 sdf0ty9776 sdf0ty76 sdf8876 sdf0t sd6 sdf06 s688876 sd688 sdf86