Как правильно писать docstring?
Правильное написание документации к функциям и классам в Python, известной как docstring, является признаком профессионального подхода к разработке и позволяет существенно упростить поддержку кода всей командой. Документация должна отвечать на главные вопросы: какую задачу решает данный фрагмент кода, какие аргументы он принимает, что возвращает в результате своей работы и какие исключения может сгенерировать при возникновении нештатных ситуаций.
Для достижения максимальной читаемости и единообразия в проекте необходимо выбрать один из устоявшихся стандартов оформления, например Google Style, NumPy Style или стандарт PEP
При составлении качественного описания функции рекомендуется следовать структуре.
Следование единому стандарту документации внутри команды избавляет от необходимости гадать о поведении функций, улучшает работу автодополнения в современных редакторах кода и IDE, а также облегчает автоматическую генерацию технической документации для всего проекта.