質問をすることでしか得られない、回答やアドバイスがある。

15分調べてもわからないことは、質問しよう!

新規登録して質問してみよう
ただいま回答率
85.50%
Python

Pythonは、コードの読みやすさが特徴的なプログラミング言語の1つです。 強い型付け、動的型付けに対応しており、後方互換性がないバージョン2系とバージョン3系が使用されています。 商用製品の開発にも無料で使用でき、OSだけでなく仮想環境にも対応。Unicodeによる文字列操作をサポートしているため、日本語処理も標準で可能です。

Q&A

解決済

2回答

19266閲覧

Pythonのdocstringにおいて、関数やクラスの引数をどう書くべきか

Alice1017

総合スコア24

Python

Pythonは、コードの読みやすさが特徴的なプログラミング言語の1つです。 強い型付け、動的型付けに対応しており、後方互換性がないバージョン2系とバージョン3系が使用されています。 商用製品の開発にも無料で使用でき、OSだけでなく仮想環境にも対応。Unicodeによる文字列操作をサポートしているため、日本語処理も標準で可能です。

0グッド

5クリップ

投稿2017/05/10 02:37

編集2017/05/10 02:45

標準ライブラリのdocstring

Pythonの標準ライブラリではdocstringが書いてありますが、ライブラリによって引数の書き方が異なっています。

たとえば os.py では

def makedirs(name, mode=0777): """makedirs(path [, mode=0777]) Super-mkdir; create a leaf directory and all intermediate ones. Works like mkdir, except that any intermediate path segment (not just the rightmost) will be created if it does not exist. This is recursive. """

このようにdocstringの一行目に引数を記載していますが、 codeop.py では

def compile_command(source, filename="<input>", symbol="single"): r"""Compile a command and determine whether it is incomplete. Arguments: source -- the source string; may contain \n characters filename -- optional filename from which source was read; default "<input>" symbol -- optional grammar start symbol; "single" (default) or "eval" Return value / exceptions raised: - Return a code object if the command is complete and valid - Return None if the command is incomplete - Raise SyntaxError, ValueError or OverflowError if the command is a syntax error (OverflowError and ValueError can be produced by malformed literals). """

このように 引数 -- 説明 の形をとっています。

また、 setuptools__init__.py では、

def find(cls, where='.', exclude=(), include=('*',)): """Return a list all Python packages found within directory 'where' 'where' is the root directory which will be searched for packages. It should be supplied as a "cross-platform" (i.e. URL-style) path; it will be converted to the appropriate local path syntax. 'exclude' is a sequence of package names to exclude; '*' can be used as a wildcard in the names, such that 'foo.*' will exclude all subpackages of 'foo' (but not 'foo' itself). 'include' is a sequence of package names to include. If it's specified, only the named packages will be included. If it's not specified, all found packages will be included. 'include' can contain shell style wildcard patterns just like 'exclude'. """

このように 引数 is 説明 の形をとっています。

標準ライブラリ以外のdocstring

標準ライブラリではないですが、有名な requests のdocstringでは、

python

1def request(method, url, **kwargs): 2 """Constructs and sends a :class:`Request <Request>`. 3 4 :param method: method for the new :class:`Request` object. 5 :param url: URL for the new :class:`Request` object. 6 :param params: (optional) Dictionary or bytes to be sent in the query string for the :class:`Request`. 7 :param data: (optional) Dictionary, bytes, or file-like object to send in the body of the :class:`Request`. 8 :param json: (optional) json data to send in the body of the :class:`Request`. 9 :param headers: (optional) Dictionary of HTTP Headers to send with the :class:`Request`. 10 :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`. 11 (以下略) 12 """

このように :param 引数: 説明 という形をとっています。

どのように書くべきか

上記でみてきたように、ライブラリによってdocstringにおける引数の書き方にはいくつかの種類があります。

Pythonにはdocstringの書き方について書いてある PEP257 がありますが、そこには

def complex(real=0.0, imag=0.0): """Form a complex number. Keyword arguments: real -- the real part (default 0.0) imag -- the imaginary part (default 0.0) """

このように書け、と書いてありましたが、Pythonistaのみなさんはどのように書くべきだと思われますでしょうか。

気になる質問をクリップする

クリップした質問は、後からいつでもMYページで確認できます。

またクリップした質問に回答があった際、通知やメールを受け取ることができます。

バッドをするには、ログインかつ

こちらの条件を満たす必要があります。

guest

回答2

0

ベストアンサー

requests はSphinxで扱える形式の"詳細情報フィールドのリスト(info field list)"で書かれています。

Python本体は、info field listに頼らずに書こうという方針が出たようで、SphinxでドキュメントをHTML化等していますがinfo field list形式では書かれていません。歴史的にはPython本体のdocstringのほうが先に存在しているというのもあります。

これ以外の書式として、Googleのdocstring形式やnumpyの形式があります。

楽に書けて、SphinxでHTML化したときに見栄えがよいのはどれか、という意味では、Python本体以外のrequests, google, numpy等のフォーマットとがよさそうですが、Sphinxを使わないのであればどれでも構わない気もします。

PEPでは、docstring内の記法までは決めていないため、今後も1つに収束する事は無いだろうなーと思います。

投稿2017/05/10 03:17

編集2017/05/10 04:22
shimizukawa

総合スコア1847

バッドをするには、ログインかつ

こちらの条件を満たす必要があります。

Alice1017

2017/05/10 05:11

ありがとうございました。 私はsphinxを使うので、今後はinfo field listで書いていこうと思います
guest

0

私はrequestsの例で示されたフォーマットで書く派です。このフォーマットで書けばPyCharmや他のIDEでも認識出来るらしいので。でも私自身は補完にあまり頼らずにdocstringを読む派なので読んで分かればなんでも良いのですが。

投稿2017/05/10 03:17

編集2017/05/10 03:19
YouheiSakurai

総合スコア6142

バッドをするには、ログインかつ

こちらの条件を満たす必要があります。

あなたの回答

tips

太字

斜体

打ち消し線

見出し

引用テキストの挿入

コードの挿入

リンクの挿入

リストの挿入

番号リストの挿入

表の挿入

水平線の挿入

プレビュー

15分調べてもわからないことは
teratailで質問しよう!

ただいまの回答率
85.50%

質問をまとめることで
思考を整理して素早く解決

テンプレート機能で
簡単に質問をまとめる

質問する

関連した質問