Документация в коде:
PEP 257, 484 и 20

§1Строки документации по PEP 257

Строка документации (docstring) — строковый литерал первой строкой модуля, класса или функции. Python сохраняет его в атрибуте __doc__, его показывают help(), подсказки редактора и генераторы документации.

PEP 257 задаёт форму: тройные двойные кавычки; первая строка — краткое описание действия в форме повеления, с точкой в конце; если нужно больше, после неё пустая строка и подробности.

def age(birth_date):
    '''
    this function returns age
    '''

def age(birth_date):
    """Вернуть полное число лет на сегодняшний день."""

def load_profile(db, user_id):
    """load_profile(db, user_id) -> dict"""

def load_profile(db, user_id):
    """Прочитать профиль ученика из базы по его идентификатору."""

def send_report(users, report_date, *, dry_run=False):
    """Отправить отчёт об активных пользователях за день.

    Пользователи без адреса почты в отчёт не попадают.

    Args:
        users: Список словарей с ключами name, email, active.
        report_date: День, за который собран отчёт.
        dry_run: Если True, отчёт собирается, но не отправляется.

    Returns:
        Код ответа сервиса отчётов или None при ошибке сети.

    Raises:
        ValueError: Если report_date в будущем.
    """

PEP 257 не задаёт, как описывать параметры. Для этого есть соглашения: стиль Google (разделы Args, Returns, Raises), стиль NumPy (подчёркнутые заголовки) и reStructuredText (:param users:). В проекте выбирают одно.

§2Аннотации типов по PEP 484

Аннотация типа — пометка, какого типа ожидается параметр, переменная или результат. Синтаксис ввёл PEP 3107, смысл аннотаций для типов — PEP 484, аннотации переменных — PEP 526, запись int | None — PEP 604.

Интерпретатор аннотации не проверяет: age("вчера") выполнится и упадёт внутри. Проверяет отдельная программа — mypy или pyright, до запуска.

def find_ticket(tickets, ticket_id):
    for t in tickets:
        if t.id == ticket_id:
            return t

def find_ticket(tickets: list[Ticket], ticket_id: int) -> Ticket | None:
    for ticket in tickets:
        if ticket.id == ticket_id:
            return ticket
    return None

$ mypy tickets.py
tickets.py:14: error: Item "None" of "Ticket | None" has no attribute "title"  [union-attr]
Found 1 error in 1 file (checked 1 source file)

§3«Дзен Python», PEP 20

PEP 20 — 19 коротких принципов, на которых построен язык. Их выводит команда import this. Линтер их не проверяет; на них ссылаются, когда решают, какой из вариантов кода выбрать.

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Errors should never pass silently.
Unless explicitly silenced.

from config import *

connect(HOST, PORT)

from config import DB_HOST, DB_PORT

connect(DB_HOST, DB_PORT)

try:
    send_email(user)
except Exception:
    pass

try:
    send_email(user)
except SMTPException:
    log.warning('письмо для %s не отправлено', user.id)
    raise