Python3 コメント

Python では、コメントはプログラムの実行に影響しませんが、コードをより読みやすく理解しやすくします。

Python のコメントには次のものがあります。単行コメントと複数行コメント。

単行コメント

Python の単行コメントは#で始まり、#記号の後のすべてのテキストはコメントと見なされ、インタプリタによって実行されません。

例

# これはコメントです
print("Hello, World!")
# これもコメントです

複数行コメント

Python では、複数行文字列（3つのシングルクォート'''または3つのダブルクォート"""で囲まれたテキストブロック）を複数行コメントとして使用できます。

1、3つのシングルクォートを使用

例

#!/usr/bin/python3

'''
これは三つのシングルクォートを使用した複数行コメントです。
これは三つのシングルクォートを使用した複数行コメントです。
これは三つのシングルクォートを使用した複数行コメントです。
'''
print("Hello, World!")

2、3つのダブルクォートを使用

例

#!/usr/bin/python3

"""
これは三つのダブルクォートを使用した複数行コメントです。
これは三つのダブルクォートを使用した複数行コメントです。
これは三つのダブルクォートを使用した複数行コメントです。
"""
print("Hello, World!")

注意：複数行文字列はここでは複数行コメントとして使用されていますが、実際には文字列であり、使用しなければプログラムの実行に影響しません。

これらの文字列はコード内のいくつかの場所に配置でき、実際の実行を引き起こさないため、コメントの効果を得られます。

複数行コメントの注意事項

Python では、複数行コメントは3つのシングルクォート'''または3つのダブルクォート"""によって定義されます。このコメント方法はネストして使用できません。。

複数行コメントブロックを開始すると、Python は別の3つのシングルクォートまたは3つのダブルクォートに遭遇するまで、後続の行をすべてコメントとして扱います。

複数行コメントのネストは構文エラーを引き起こします：

例（誤った例）

'''
これは外部の複数行コメントです
記述べたな内容を含むことができます

    '''
これはネストされた複数行コメントを試しています
会导致语法错误
    '''
'''

この例では、内部の3つのシングルクォートは複数行コメントの終了として正しく認識されず、通常の文字列として解釈されるため、コード構造が正しくなくなります。

正しい方法：単行コメントを使用してネストする

例（正しい例）

'''
これは外部の複数行コメントです
記述べたな内容を含むことができます

# これは内部の単行コメントです
# 複数行コメント内にネストできます
'''

Docstring ドキュメント文字列

Python の Docstring（ドキュメント文字列）は、関数、クラス、モジュールなどにドキュメント説明を追加するための特別なコメントです。Java の Javadoc に似ていますが、より強力で柔軟です。

通常のコメントとは異なり、Docstring は__doc__属性から直接アクセスでき、またhelp()関数で表示できます。

基本構文

Docstring は3つのダブルクォート"""または3つのシングルクォート'''で囲み、関数、クラス、モジュールの先頭に配置します。

例

def add(a, b):
    """二つの数のとを返す"""
    return a + b

# 通过 __doc__ 属性访问
print(add.__doc__)  # 出力: 二つの数のとを返す

help() を使用してドキュメントを表示

例

def add(a, b):
    """二つの数のとを返す"""
    return a + b

# 使用 help() 函数
help(add)

実行結果の予想:

Help on function add in module __main__:

add(a, b)
    返回两数之和

inspect モジュールを使用してドキュメントを抽出

Python の標準ライブラリにはinspectモジュールがあり、ドキュメントの内容を直接抽出できます：

例

import inspect

def add(a, b):
    """二つの数のとを返す"""
    return a + b

# 使用 inspect.getdoc() 获取文档
print(inspect.getdoc(add))  # 出力: 二つの数のとを返す

実行結果の予想:

二つの数の合計を返す

複数行Docstring

複雑な関数の場合は、複数行 Docstring を使用できます：

例

def calculate(a, b, operation="add"):
    """
执行数学运算

参数:
a: 第一个数字
b: 第二个数字
operation: 操作类型，可选 "add", "subtract", "multiply"

返回:
计算结果
    """
    if operation == "add":
        return a + b
    elif operation == "subtract":
        return a - b
    elif operation == "multiply":
        return a * b
    else:
        raise ValueError("サポートされていない操作")

# 查看完整文档
help(calculate)

実行結果の予想:

Help on function calculate in module __main__:

calculate(a, b, operation='add')
    执行数学运算

    引数:
        a: 第一个数字
        b: 第二个数字
        operation: 操作类型，可选 "add", "subtract", "multiply"

    返回:
        计算结果

クラスの Docstring

Docstring はクラスにも使用できます：

例

class Person:
    """人物クラス。個人の基本情報を表すために使用します。"""

    def __init__(self, name, age):
        """
人物オブジェクトを初期化する

参数:
name: 姓名
age: 年龄
        """
        self.name = name
        self.age = age

    def introduce(self):
        """この人を紹介する"""
        return f"我叫{self.name}，今年{self.age}岁"

# クラスのドキュメントにアクセスする
print(Person.__doc__)

# メソッドのドキュメントを参照
print(Person.introduce.__doc__)

実行結果の予想:

人物クラス。一人の人の基本情報を表すために使用する
この人を紹介する

Docstring の規範

Python には複数の Docstring スタイルがあり、よく使われるものは次のとおりです：

  • Google スタイル：スペースでインデントし、パラメータと戻り値に明確なラベルを付けます。
  • Sphinx/reST スタイル：コロンで始めます。例：:param name:。
  • NumPy スタイル：Google スタイルと似ていますが、形式が少し異なります。

プロジェクトでは1つのスタイルを選択し、一貫性を保つことをお勧めします。

その他の拡張