3 вещи, которые вам нужно практиковать, чтобы правильно документировать свой код Python
Я уверен, что вы все читали о важности документирования вашего кода. Как специалист по данным, я обычно использую блокноты Jupiter во время разработки, и записей там мне достаточно.
Но, не буду врать, когда я вернусь к этому через несколько недель, чтобы перевести код в производство, мне пришлось почесать голову слишком много раз, чем я готов признать. Кроме того, это может быть проблемой, когда вы работаете в команде или передаете ее другой команде. 😅
Мелочи, которые вы забываете добавлять в свои заметки Jupyter, могут вызвать самую большую головную боль.
В этой статье я расскажу о 3 вещах, которые вам нужно знать/практиковать, чтобы ваша документация была максимально полной.
1. Комментарии
Всегда добавляйте соответствующие комментарии к вашему коду, где это возможно. И будьте осторожны, чтобы не переусердствовать, добавляя комментарии ко всему. Лучшие комментарии — это те, которые вам не нужно писать, так как код очень понятен.
Вообще говоря, есть два типа комментариев: однострочные и многострочные комментарии. В Python комментирование обычно делается с использованием символа хэштега (#) перед комментарием.
Однако для многострочных комментариев вы также можете использовать метод многострочного строкового литерала (''' '''). Поскольку строковый литерал не назначен какой-либо переменной, интерпретатор Python просто проигнорирует его; поэтому действует как комментарий.
Должен ли я использовать стиль хэштега или стиль строкового литерала для многострочных комментариев? Просто выберите стиль и придерживайтесь его. Лично я хожу с хэштегами, потому что я человек склонный к ошибкам 😅.
Если вы не будете осторожны со стилем комментирования строкового литерала, вы можете случайно превратить комментарий в строку документации, что только запутает документацию.
Как вы решаете, когда уместно добавить комментарии? Я использую эту простую цитату из Джеффа как полярную звезду.
Код может только сказать вам, как работает программа; комментарии могут сказать вам, почему это работает. — Джефф Этвуд
Принимая решение о добавлении комментариев, спросите себя, объясняет ли код причину этого. Если вопрос «почему» неоднозначен или сложен для расшифровки с первого взгляда, он может быть хорошим кандидатом для некоторых старых добрых комментариев. 👍
2. Явная типизация
Будьте максимально откровенны в своем коде. Это будет иметь большое значение для устранения любой двусмысленности в будущем. Я уверен, что все вы ясны и ясны в своих объявлениях переменных, но не многие ясны в своих определениях функций.
Изображение ниже является примером явного ввода при определении функции.
Из сигнатуры приведенного выше определения функции, благодаря явной типизации, мы можем многое сказать о входных и выходных данных функции. Например:
The function has 3 inputs: 1. A variable called Dimensions of type List. 2. A variable called shape of type string. 3. A variable called unit_type of type string with default value called 'metric'. The function also has a return value of type float.
Видите, как это информативно? 😄 Просто взглянув на эту подпись, мы можем многое сказать о функции.
3. Строки документации
Строки документации — ваши лучшие друзья, когда дело доходит до документации. Они обеспечивают стандартизированный способ определения общей полезности, аргументов, исключений и многого другого.
Если вы используете Visual Studio Code, установите расширение Python Docstrings Generator. Это значительно упростит документирование!
Все, что вам нужно сделать, это ввести """ под функцией и нажать клавишу Shift. Затем он сгенерирует шаблон строки документации и автоматически заполнит части строки документации, используя информацию о типе.
Совет: сделайте строки документации после завершения функции. Таким образом, он будет автоматически заполнять как можно больше, включая возвращаемые типы, исключения и т. д.
В качестве примера давайте применим строки документации к определению функции, которое мы использовали в предыдущем разделе.
Посмотрите, как расширение docstrings в VS Code автоматически создает некоторую документацию, используя информацию из сигнатуры функции. В нем также выделяются части, которые необходимо просмотреть, чтобы ваша документация была завершена.
После того, как вы подготовили строки документации для проекта, вы можете превратить его в простой и элегантный статический веб-сайт с помощью mkdocs. Подробнее об этом как-нибудь в другой раз.
PS: не обращайте внимания на волнистую линию под возвращаемым значением Volume. Это проявляется, потому что я не объявил переменную громкости в функции.😅
Последние мысли
Документирование вашего может иметь большое значение. Это не только помогает другим понять, что делает код, но также делает вас лучшим разработчиком, заставляя вас переосмыслить свой код, вынуждая вас применять некоторую стандартизацию ко всем вашим файлам и делая вас лучшим коммуникатором.
Сначала документирование может показаться дополнительной проблемой. Но если вы попрактикуетесь в пунктах, упомянутых в этой статье, и используете некоторые расширения в своей среде IDE, через некоторое время это станет простым и привычным делом. 😃
Надеюсь, эта статья оказалась для вас полезной. Свяжитесь со мной, если у вас возникнут вопросы или вы думаете, что я могу помочь.
Вы также можете связаться со мной в Twitter. 😄
Вам также могут понравиться следующие мои статьи:
