Комментарии Python3

В Python комментарии не влияют на выполнение программы, но делают код более читаемым и понятным.

Комментарии в Python включают:Однострочные комментариииМногострочные комментарии。

Однострочные комментарии

В Python однострочные комментарии используют## в начале,#Весь текст после символа # рассматривается как комментарий и не выполняется интерпретатором.

Пример

# Это комментарий
print("Hello, World!")
# Это тоже комментарий

Многострочные комментарии

В Python многострочные строки (текстовые блоки, заключённые в три одинарные кавычки'''или три двойные кавычки""") можно использовать как многострочные комментарии.

1. Использование трёх одинарных кавычек

Пример

#!/usr/bin/python3

'''
Это многострочный комментарий с использованием трёх одинарных кавычек
Это многострочный комментарий с использованием трёх одинарных кавычек
Это многострочный комментарий с использованием трёх одинарных кавычек
'''
print("Hello, World!")

2. Использование трёх двойных кавычек

Пример

#!/usr/bin/python3

"""
Это многострочный комментарий с использованием трёх двойных кавычек
Это многострочный комментарий с использованием трёх двойных кавычек
Это многострочный комментарий с использованием трёх двойных кавычек
"""
print("Hello, World!")

Примечание: Хотя многострочные строки здесь используются как многострочные комментарии, на самом деле они являются строками. Пока мы их не используем, они не повлияют на выполнение программы.

Эти строки можно разместить в некоторых местах кода без фактического выполнения, таким образом достигая эффекта комментариев.

Примечания о многострочных комментариях

В Python многострочные комментарии определяются тремя одинарными кавычками'''или тремя двойными кавычками"""для определения,Этот тип комментария не может быть вложенным.。

Когда вы начинаете блок многострочного комментария, Python будет рассматривать все последующие строки как комментарии, пока не встретит ещё один набор из трёх одинарных кавычек или трёх двойных кавычек.

Вложение многострочных комментариев вызовет синтаксические ошибки:

Пример (неправильный)

'''
Это внешний многострочный комментарий
Он может содержать некоторое описательное содержимое

    '''
Это попытка вложить многострочный комментарий
Это вызовет синтаксическую ошибку
    '''
'''

В этом примере внутренние три одинарные кавычки не распознаются правильно как конец многострочного комментария, а интерпретируются как обычная строка, что приведёт к неправильной структуре кода.

Правильный подход: использовать однострочные комментарии для вложенности

Пример (правильно)

'''
Это внешний многострочный комментарий
Он может содержать некоторое описательное содержимое

# Это внутренний однострочный комментарий
# Его можно вложить в многострочный комментарий
'''

Docstring (строки документации)

Docstring в Python (строка документации) — это специальный комментарий, используемый для добавления документации к функциям, классам, модулям и т. д. Он похож на Javadoc в Java, но более мощный и гибкий.

В отличие от обычных комментариев,к строкам документации можно получить доступ напрямую через__doc__атрибут __doc__,или можно использоватьhelp()функцию help() для просмотра.

Базовый синтаксис

Строки документации используют три двойные кавычки"""или три одинарные кавычки'''чтобы заключить их, и размещаются в начале функции, класса или модуля.

Пример

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модуль inspect, который может напрямую извлекать содержимое документации:

Пример

import inspect

def add(a, b):
    """Возвращает сумму двух чисел"""
    return a + b

# Используйте inspect.getdoc() для получения документации
print(inspect.getdoc(add))  # Вывод: Возвращает сумму двух чисел

Ожидаемый вывод:

Return the sum of two numbers

Многострочная строка документации

Для сложных функций можно использовать многострочные строки документации:

Пример

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')
    执行数学运算

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

    返回:
        计算结果

Строка документации класса

Строки документации также можно использовать для классов:

Пример

class Person:
    """Класс Person, используемый для представления основной информации о человеке"""

    def __init__(self, name, age):
        """
Инициализировать объект person

Параметры:
name: Имя
age: Возраст
        """
        self.name = name
        self.age = age

    def introduce(self):
        """Представить этого человека"""
        return f"Меня зовут {self.name}, и мне {self.age} лет"

# Доступ к документации класса
print(Person.__doc__)

# Доступ к документации метода
print(Person.introduce.__doc__)

Ожидаемый вывод:

Person class, used to represent basic information about a person
Introduce this person

Соглашения по docstring

В Python существует несколько стилей docstring. Распространённые из них включают:

  • Стиль Google: использует пробелы для отступов, с чёткими метками для параметров и возвращаемых значений.
  • Стиль Sphinx/reST: использует двоеточие в начале, например:param name:。
  • Стиль NumPy: похож на стиль Google, но с немного другим форматированием.

Рекомендуется выбрать один стиль в вашем проекте и придерживаться его.

Другие расширения