Глава 6. Документирование кода

AI. "Кожа". Эмблема Python

Предыдущая статья:

Комментарии

При написании программы вы можете (вам необходимо!) включать в текст кода пояснения: для чего предназначен тот или иной фрагмент кода, на что следует обратить внимание, почему вы используете именно такой код и прочее.

Это к о м м е н т а р и и, они не влияют на исполнение кода и представляет интерес лишь как заметки программисту.

Не ленитесь включать в программу комментарии, старайтесь писать их максимально понятно: для тех, кто будет читать код (и вы сами, в том числе, по прошествии некоторого времени!), легче будет понять, что программа делает.

Чтобы комментарии «не видела»программа, их предваряет символ «решётка», он же «хэштег»(«#»).

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

Это ещё одна «фишка» Python. С т р о к и д о к у м е н т а ц и и* тоже несут на себе пояснительную функцию.

* DocString - от англ. «Documentation String» – «строка документации».

Отличие их от комментариев в том, что docstring могут быть получены даже в ходе выполнения программы.

Строки документации заключаются в т р о й н ы е кавычки.

Доступ к строке документации функции можно получить с помощью «__doc__» (обратите внимание на д в о й н о е нижнее подчёркивание до и после «doc»).

Также для получения документации в Pythonвсегда можно задействовать функцию «help()» (docstring.py).

[Чтобы редактор VSC работал корректно, не ленитесь сохранять код перед запуском («Ctrl+S») и очищать терминал («Корзина») по завершении.]

Имейте в виду, строки документации будут выводиться т о л ь к о по вашей команде!

С помощью пресловутого хэштега («#») я «отключил» в предыдущем сценарии команды доступа к docstring («__doc__» и «help()»), и вот что получилось (docstring.py):

Программа не вывела строки документации, поскольку команды доступа к docstring, "благодаря" хэштегу («#»), стали просто комментариями. :-)

Записывать docstring принято в многострочной форме, где первая строка начинается с заглавной буквы и заканчивается точкой. Вторая строка оставляется пустой, а подробное описание начинается с третьей.

Рекомендовано следовать такому формату для всех строк документации всех ваших нетривиальных функций (а также классов/типов данных, модулей).

Аннотации

А н н о т а ц и и – ещё одна возможность информировать о различных аспектах кода. Например, они позволяют указывать, какой тип данных может принимать переменная или какой тип данных должен быть получен на выходе функции. Сообщают они и о требованиях, предъявляемых к тому или иному типу. Аннотации повышают читабельность кода и помогают уберечься от ошибок.

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

Поскольку аннотации относятся к вспомогательным инструментам, более подробно о них в рамках этого курса распространяться не буду. Просто помните, что такой функционал существует.

ПИШИТЕ КАК МОЖНО БОЛЬШЕ КОДА!

Последующая статья: