pydoc と複数行コメントの書き方

20161209

Python 書き始めて正味 3 日の Perl 使い

普段のコメントについての結論

''' は、ヒアドキュメント代替以外としては、 pydoc のためだけに存在すると割り切って、それ以外のすべてのコメントは #　でごりごり書くことにしよ¹。

コード

• 2.6, 2.7, 3.4 で確認
• お作法的な意味での、関数のネストとか、if ブロック内の class とかの可否は、考慮せず

foo.py

#!/usr/bin/env python
# -*- encoding: utf-8 -*-
'''
about NAME

DESCRIPTION
'''

__author__  = 'bunzaemon'
__version__ = '1.0'
__date__    = '2016/12/09'

x = 42
print (x)
'IGNORED comment'

def foo ():
    # of course ignored
    'DEF: foo'
    'IGNORED comment'
    def bar ():
        'DEF: bar <= IGNORED'

class Clas:
    'CLASS: Clas'
    def __init__ (self):
        'CLASS DEF: __init__'

if 1:
    'IGNORED comment'
    y = 42
    print (y)
    def buz ():
        'DEF: buz'
        def bux ():
            'IGNORED comment'
    class Clas2:
        'CLASS: Clas2'

if 0:
    z = 42
    print (z)
    class Clas3:
        'IGNORED comment'

実行結果

• u'...' はダメ => 2.6 系ではコケる。²
• IGNORED comment を当てにしてコメントを書くと混乱させそう。³

$ python --version
Python 2.6.6
$ python ./foo.py
42
42
$ pydoc ./foo.py
Help on module foo:

NAME
    foo - about NAME

FILE
    /PATH/TO/foo.py

DESCRIPTION
    DESCRIPTION

CLASSES
    Clas
    Clas2

    class Clas
     |  CLASS: Clas
     |
     |  Methods defined here:
     |
     |  __init__(self)
     |      CLASS DEF: __init__

    class Clas2
     |  CLASS: Clas2

FUNCTIONS
    buz()
        DEF: buz

    foo()
        DEF: foo

DATA
    __author__ = 'bunzaemon'
    __date__ = '2016/12/09'
    __version__ = '1.0'
    x = 42
    y = 42

VERSION
    1.0

DATE
    2016/12/09

AUTHOR
    bunzaemon

1. pydoc のソース自体が、そう書かれてるし、、、。せめて、perl の =begin, =end, =cut みたく指定できればな、、、 ↩

2. 2.6 系考えなくてよい人はつけたほうがいい。 ↩

3. 将来の自分を ↩