Что такое строка документации (docstring)?

1. Что такое docstring

• Docstring — это строка документации, которая описывает модуль, класс или функцию.

• Она помогает понять, что делает код, без необходимости смотреть его реализацию.

• В Python docstring оформляется с помощью тройных кавычек ("""…""").

---

2. Синтаксис

def функция():
    """Описание того, что делает функция"""
    pass

Примеры:

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

class User:
    """Класс для работы с пользователями системы"""
    def __init__(self, name):
        """Инициализация пользователя с именем name"""
        self.name = name

---

3. Где используется

• В начале модуля, класса, функции.

• Для генерации автоматической документации (help(), Sphinx, pydoc).

help(add)

Вывод:

Help on function add in module __main__:

add(a, b)
    Возвращает сумму двух чисел a и b.

---

4. Правила написания docstring (PEP 257)

• Использовать тройные кавычки.

• Однострочные docstring — короткое описание, без точки в конце:

  """Возвращает сумму двух чисел"""

• Многострочные docstring:

  """
  Выполняет подключение к базе данных.
  Параметры:
      host: адрес сервера
      port: порт подключения
  """

• Начало с заглавной буквы.

---

5. Применение в автоматизации тестирования

• Документирование тестов, функций-утилит, Page Object:

def login(username, password):
    """Выполняет вход на сайт с указанными username и password"""
    pass

• Позволяет использовать help(login) или автоматически генерировать документацию по тестам.