Python プログラムに入れるコメント形式 docstrings についてメモ

PEP 257 で docstrings の規定はあるんだけど、 コメント内容の形式には様々な表現・記述形式がある、ということで。

Python documentation standard for docstring - Stack Overflow

reST の形式だと :単語:定義 でフィールドリストになるので、それにならう方法が良いのでは、というハナシ。そして、PyCharm が対応しているのもコチラというハナシを聞いた気がする。

Python - PyCharm での type hinting を使いこなす - Qiita

他、

Google Python Style Guide

を見ると、

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}

        If a key from the keys argument is missing from the dictionary,
        then that row was not found in the table.

    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """
    pass

(Google Python Style Guide から引用)

という形式なのだけど、

Sphinx 形式だと、

"""replaces template place holder with values

:param timestamp: formatted date to display
:type timestamp: str or unicode
:param priority: priority number
:type priority: str or unicode
:param priority_name: priority name
:type priority_name: str or unicode
:param message: message to display
:type message: str or unicode
:returns: formatted string
:rtype: str or unicode
"""

(Python documentation standard for docstring - Stack Overflow から引用)

という形式になる。

PyCharm でのタイプヒンティングについては、

Type Hinting in PyCharm

に書かれているんだけど…。

うーん統一的なのはない、ということで…。とりあえずメモ