Python Language
コメントとドキュメント
サーチ…
構文
- ＃これは一行のコメントです
- print（ ""）＃これはインラインコメントです
- ""
これは
複数行のコメント
""
備考
開発者はPEP257 - Docstring Conventionsのガイドラインに従う必要があります。場合によっては、スタイルガイド（ Googleスタイルガイドなど）やサードパーティレンダリング（ Sphinxなど）でドキュメントストリングの追加規則を詳しく説明することもあります。
単一行、インライン、複数行コメント
コメントは、基本コード自体が明確でない場合にコードを説明するために使用されます。
Pythonはコメントを無視するので、そこでコードを実行したり、普通の英語の文章の構文エラーを起こしたりすることはありません。
単一行のコメントは、ハッシュ文字（ # ）で始まり、行末で終わります。
- 一行コメント：
# This is a single line comment in Python
- インラインコメント：
print("Hello World") # This line prints "Hello World"
- 複数の行にまたがるコメントは、どちらかの端に
"""または'''を持ちます。これは複数行の文字列と同じですが、コメントとして使用できます。
"""
This type of comment spans multiple lines.
These are mostly used for documentation of functions, classes and modules.
"""
プログラミングによるdocstringへのアクセス
ドキュメントストリングは、通常のコメントと異なり、ドキュメントの属性として格納されているため、プログラマチックにアクセスできます。
関数の例
def func():
"""This is a function that does nothing at all"""
return
docstringには、 __doc__属性を使用してアクセスできます。
print(func.__doc__)
これは何もしない関数です
help(func)
モジュール
__main__関数funcに関するヘルプ：
func()これは何もしない関数です
別の関数例
function.__doc__は文字列としての実際のdocstringであり、 help関数はdocstringを含む関数に関する一般的な情報を提供します。もっと役に立つ例があります：
def greet(name, greeting="Hello"):
"""Print a greeting to the user `name`
Optional parameter `greeting` can change what they're greeted with."""
print("{} {}".format(greeting, name))
help(greet)
機能のヘルプモジュール
__main__greet：
greet(name, greeting='Hello')ユーザー
nameグリーティングを印刷する
オプションのパラメータgreetingは、greetingを変更することができます。
定期的なコメントよりもdocstringsのメリット
関数にdocstringや普通のコメントを入れないだけで、それほど役に立たなくなります。
def greet(name, greeting="Hello"):
# Print a greeting to the user `name`
# Optional parameter `greeting` can change what they're greeted with.
print("{} {}".format(greeting, name))
print(greet.__doc__)
無し
help(greet)
機能のヘルプモジュールメインで挨拶：
greet(name, greeting='Hello')
docstringを使ってドキュメントを書く
docstringは、モジュール、クラス、関数、メソッドを記述するために使用される複数行のコメントです。これは、それが記述するコンポーネントの最初のステートメントでなければなりません。
def hello(name):
"""Greet someone.
Print a greeting ("Hello") for the person with the given name.
"""
print("Hello "+name)
class Greeter:
"""An object used to greet people.
It contains multiple greeting functions for several languages
and times of the day.
"""
docstringの値は、 プログラム内でアクセスすることができます 。たとえば、 helpコマンドで使用しhelp 。
構文規則
PEP 257
PEP 257は、docstringコメントの構文標準を定義しています。基本的に2つのタイプがあります：
- One-line Docstrings：
PEP 257によれば、それらは短くて単純な機能と共に使用されるべきです。すべてが1行に表示されます。例：
def hello():
"""Say hello to your friends."""
print("Hello my friends!")
文章題はピリオドで終わらなければならず、動詞は必須の形でなければならない。
- 複数行のドキュメントストリング：
より長い、より複雑な関数、モジュールまたはクラスには、複数行のドキュメントストリングを使用する必要があります。
def hello(name, language="en"):
"""Say hello to a person.
Arguments:
name: the name of the person
language: the language in which the person should be greeted
"""
print(greeting[language]+" "+name)
それらは、引用符と同じ行にあるか、次の行にあることができる短い要約（1行のドキュメントストリングの内容に相当）から始まり、追加の詳細およびリストパラメーターと戻り値を与えます。
Note PEP 257は、ドキュメントストリング内でどの情報を与えなければならないかを定義するものであり、どのフォーマットで与えられるべきかを定義していない。これは、他の関係者や文書解析ツールが文書化のための独自の基準を指定する理由であり、そのいくつかは以下およびこの質問に列挙されています。
スフィンクス
Sphinxは、ドキュメントストリングに基づいてPythonプロジェクト用のHTMLベースのドキュメントを生成するツールです。使用されるマークアップ言語はreStructuredTextです。彼らはドキュメンテーションのための独自の標準を定義しています。pythonhosted.org はそれらの非常に良い説明を提供しています 。 Sphinx形式は、たとえばpyCharm IDEで使用されます。
関数は、Sphinx / reStructuredText形式を使用して次のように文書化されます。
def hello(name, language="en"):
"""Say hello to a person.
:param name: the name of the person
:type name: str
:param language: the language in which the person should be greeted
:type language: str
:return: a number
:rtype: int
"""
print(greeting[language]+" "+name)
return 4
Google Pythonスタイルガイド
Googleは、Pythonのコーディング規則を定義するGoogle Python Style Guideを公開しました 。 Sphinx / reSTと比較して、多くの人が、Googleのガイドラインに従ったドキュメントは人間が読めるように優れていると言います。
上記のpythonhosted.orgページには、Googleスタイルガイドに従って適切なドキュメントの例がいくつか用意されています。
Sphinxは、 Napoleonプラグインを使用して、Googleスタイルガイドに準拠した形式でドキュメントを解析することもできます。
関数は、Google Style Guideフォーマットを使用して次のように文書化されます。
def hello(name, language="en"):
"""Say hello to a person.
Args:
name: the name of the person as string
language: the language code string
Returns:
A number.
"""
print(greeting[language]+" "+name)
return 4
