Документируя свой путь к лучшему тестам в Python

Запись и код чтения

Код написания жесткий, код чтения сложнее

Я участвую в большом количестве отзывов кода, и одна вещь, которую я понял, – это – разработчики проводят большую часть своего времени, кодирующего решение, не достаточно времени, объясняя его.

Есть два способа, которыми вы могли бы объяснить, как работает ваш код:

1. Напишите простой код, который является самоснабжением
2. Напишите «хорошую» документацию

Значение хорошей документации

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

Позвольте мне проиллюстрировать с примером.

Я определил my_function Ниже, что вычисляет некоторую «произвольную» логику:

def my_function(input_string, input_list=None):
    head = "Start:"
    tail = "" if not input_list else " ".join(input_list)
    output = f"{input_string} {tail}"
    if not input_string.startswith(head):
        output = f"{head} {input_string} {tail}"

    return output.strip()

В реальной проблеме этот кусок кода может быть гораздо более сложным.

Как читатель, вы можете прочитать этот код и понять, что он делает. Тем не менее, я могу сделать работу читателя проще, используя DOCSTRING Отказ

DocStrings: сделать код легко читать

DOCSTRING имеет огромное значение при разработке кода в большой организации и/или в совместном сообществе.

Это позволяет какому-либо разработчику понять, что происходит в функции/модуле без них, чтобы прочитать через всю кодовую базу.

Это также может быть использовано с инструментами, такими как Sphinxdoc Для создания красивой документации для вашего проекта.

def my_function(input_string, input_list=None):
    """Sanitize input string and append extra text if required

    The function checks if input_string starts with 'Start:' 
    if not, it will add the string to the input_string 

    It also converts input_list to a string using join 
    and appends to the input_string
    """
    head = "Start:"
    tail = "" if not input_list else " ".join(input_list)
    output = f"{input_string} {tail}"
    if not input_string.startswith(head):
        output = f"{head} {input_string} {tail}"

    return output.strip()

DOCSTRING в вышеуказанном коде объясняет, что делает код, но он все же чувствует себя как повторение того, что написано в блоке кода.

Как мы улучшаем это? Использование доктра Действительно

Докт: прочитайте, тестируйте и документы лучше

доктра Позволяет не только проверять интерактивные примеры Python, но также также гарантирует, что ваша документация обновлена.

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

def my_function(input_string, input_list=None):
    """Sanitize input string and append extra text if required

    >>> my_function('hi')
    'Start: hi'

    >>> my_function('Start: some string')
    'Start: some string'

    >>> my_function('hi', ['other', 'item'])
    'Start: hi other item'

    :param input_string: string to sanitize
    :type input_string: str
    :param input_list: extra items to append, defaults to None
    :type input_list: list, optional
    :return: sanitized string
    :rtype: str
    """
    head = "Start:"
    tail = "" if not input_list else " ".join(input_list)
    output = f"{input_string} {tail}"
    if not input_string.startswith(head):
        output = f"{head} {input_string} {tail}"

    return output.strip()

Здесь я определил некоторые примеры ввода-вывода для заданной функции, которая иллюстрирует то, что делает функция. Например:

my_function('hi', ['other', 'item'])

должен вернуться:

'Start: hi other item'

Вышеуказанная документация говорит разработчикам/читателям следующее:

• Что делает функция
• Параметры и их типы
• Возвращаемое значение и его тип
• Ожидаемое поведение – описывает примеры ввода/вывода

Заключение

Генерация документации

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

Практикующий TDD

Написание документации в Python также позволяет мне следовать разработке тестирования, где я впервые определяю поведение в DOCSTRING Затем напишите код.

доктра Может выполняться любыми тестированными рамками, такими как Неизвестный или питиш

$ pytest --doctest-modules -vv top.py
=================== test session starts ======================
platform darwin -- Python 3.8.2, pytest-6.2.4 
-- /projects/virtualenvs/dev-to/bin/python3
cachedir: .pytest_cache
rootdir: /Users/chaitanyadwivedi/projects/dev-to
collected 1 item                                                                                                                                           

top.py::top.my_function PASSED                          [100%]

==================== 1 passed in 0.05s =======================

Оригинал: “https://dev.to/chaitdwivedi/documenting-your-way-to-better-tests-in-python-h5n”