Какие знаешь способы документации кода Python?

Способы документации кода Python

Документация — это критически важная часть профессионального кода. В Python есть несколько стандартных способов документировать код на разных уровнях.

1. Docstrings (строки документации)

Самый распространённый способ. Это строки в начале модуля, класса или функции, заключённые в тройные кавычки:

def calculate_average(numbers):
    """
    Вычисляет среднее арифметическое списка чисел.
    
    Args:
        numbers (list): Список чисел для вычисления.
    
    Returns:
        float: Среднее значение чисел.
    
    Raises:
        ValueError: Если список пуст.
    """
    if not numbers:
        raise ValueError("Список не может быть пустым")
    return sum(numbers) / len(numbers)

Доступ к docstrings:

print(calculate_average.__doc__)
help(calculate_average)

2. Стили docstrings

Google Style

def function(arg1, arg2):
    """Краткое описание.
    
    Более подробное описание функции.
    
    Args:
        arg1 (str): Описание arg1.
        arg2 (int): Описание arg2.
    
    Returns:
        bool: Описание возвращаемого значения.
    
    Raises:
        ValueError: Когда возникает ошибка.
    """
    pass

NumPy Style

def function(arg1, arg2):
    """Краткое описание.
    
    Подробное описание.
    
    Parameters
    ----------
    arg1 : str
        Описание arg1.
    arg2 : int
        Описание arg2.
    
    Returns
    -------
    bool
        Описание возвращаемого значения.
    
    Raises
    ------
    ValueError
        Когда возникает ошибка.
    """
    pass

reStructuredText (Sphinx)

def function(arg1, arg2):
    """Краткое описание.
    
    :param arg1: Описание arg1
    :type arg1: str
    :param arg2: Описание arg2
    :type arg2: int
    :return: Описание результата
    :rtype: bool
    :raises ValueError: Когда возникает ошибка
    """
    pass

3. Комментарии в коде

Используются для объяснения как код работает, а не что он делает:

def calculate_hash(data):
    # Используем SHA-256 для криптографической безопасности
    result = hashlib.sha256(data.encode()).hexdigest()
    return result

4. Inline комментарии

Для очень специфичных участков кода:

x = y + 5  # Добавляем смещение в 5 пикселей
threshold = value * 0.95  # Оставляем 5% запас

5. Type hints (подсказки типов)

Python 3.5+ поддерживает type hints, которые служат документацией и помогают инструментам анализа:

from typing import List, Dict, Optional

def process_users(users: List[Dict[str, str]]) -> Optional[str]:
    """Обрабатывает список пользователей.
    
    Args:
        users: Список словарей с данными пользователя.
    
    Returns:
        Имя первого пользователя или None.
    """
    if not users:
        return None
    return users[0].get("name")

6. Документация классов

class DataProcessor:
    """Класс для обработки данных.
    
    Attributes:
        config (dict): Конфигурация обработчика.
        cache (dict): Кэш результатов.
    """
    
    def __init__(self, config: dict):
        """Инициализирует процессор.
        
        Args:
            config: Словарь конфигурации.
        """
        self.config = config
        self.cache = {}
    
    def process(self, data: str) -> str:
        """Обрабатывает входные данные.
        
        Args:
            data: Строка для обработки.
        
        Returns:
            Обработанная строка.
        """
        return data.upper()

7. README файлы и документация проекта

На уровне проекта используются отдельные файлы:

project/
├── README.md           # Основная документация
├── CONTRIBUTING.md     # Правила контрибуции
├── docs/
│   ├── installation.md
│   ├── usage.md
│   └── api.md
└── CHANGELOG.md        # История изменений

8. Sphinx и автоматическая документация

Инструмент для генерации HTML документации из docstrings:

sphinx-quickstart docs
sphinx-build -b html docs/source docs/build

9. Примеры в docstrings (doctests)

def add(a, b):
    """Складывает два числа.
    
    Examples:
        >>> add(2, 3)
        5
        >>> add(-1, 1)
        0
    """
    return a + b

Запуск doctests:

python -m doctest mymodule.py

10. Файл CHANGELOG

Отслеживание изменений версий:

## [1.2.0] - 2024-03-20
### Added
- Новая функция для фильтрации данных

### Fixed
- Исправлена ошибка в обработке пустых списков

### Changed
- Улучшена производительность парсера