Чистый код на Python. Документация из кода

Пилим юзер гайд из комментариев
Photo by Christina Morillo

РубрикаСложность материалаСРЕДНЯЯВремя на чтение10 минут

Ingredients

Directions

Чистый код на Python. Документация из кода

Правилом хорошего тона в Python является легко читаемый код. Рекомендации по нему содержаться в документе PEP — Python Enhancement Proposals, что расшифровывается как Предложения по развитию Python. Конкретно используется PEP-8 — там обозначены правила написания кода, его общий дизайн и стиль. Данные рекомендации не обязательны, но очень желательны для тех, кто считает себя хорошим разработчиком.

Чистый код

1) Отступы

Для отступа необходимо использовать 4 пробела или табуляцию (отступ с помощью клавиши TAB). При этом нельзя смешивать символы табуляции и пробелы. Считается, что использование «обычных» пробелов

def __init__(self, database, account_name):
    super().__init__()
    self.database = database
    self.account_name = account_name

 

2) Максимальная длина строки

Ограничение максимальной длины строки установлено 79 символами. В многих IDE в интерфейсе есть полоса, которая визуально позволяет контролировать моменты, когда строка выходит за допустимый предел. Это и комментариев касается, между прочим:

Иногда потребуется настройка этого параметра, т.к. в том же PyCharm, по умолчанию, стоит лимит в 120 символов. Чтобы установить ограничение в 79 символов необходимо зайти в настройки (File -> Settings). Выбираем категорию Editor и пункт Code Style. В нём уже меняем параметр Hard wrap at на 79

3) Пустые строки между функциями и классами

Необходимо отделять классы и функции верхнего уровня (функции внутри функции — не в счет) двумя пустыми строками. Это придает коду большую читабельность.

4) «Правильный» import модулей

Импорт каждого отдельного модуля должен начинаться с новой строки

5) Пробелы и там, где они не нужны

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

# правильный вариант написания
test(chiken[1], {eggs: 2})

# неправильный вариант написания
test( chiken[ 1 ], { eggs: 2 } )

# правильный вариант написания
if x == 100: x, y = y, x

# неправильный вариант написания
if x == 100 : x , y = y , x

# правильный вариант написания
text(arg)

# неправильный вариант написания
text (arg)

# правильный вариант написания
dict['key'] = list[index]

# неправильный вариант написания
dict ['key'] = list [index]

 

Комментарии

Главное правило, которое стоит учесть при работе с комментариями — всегда вносите исправления в комментарии, если вы что-то изменили в коде. Отсутствие комментариев лучше, чем устаревшие данные по коду в них. Блок комментариев обычно состоит из одного или более абзацев, составленных из полноценных предложений — не обрезайте их на половине.

Что касается блоков комментариев — они должны иметь тот же отступ, что и сам код, который вы комментируете. Новая строчка блока начинается с символа решетки #. После # должен быть один пробел. В самом коде, в той же самой строчке, оставлять комментарии не рекомендуется, но, в принципе, «правилами» не запрещено.

Имена и как их писать

Правильно именовать переменные или функции — тоже работа программиста. Здесь есть свои правила хорошего тона — например, нельзя использовать латинские буквы l,I и O для идентификаторов переменных. Связано это с их плохой «узнаваемостью» в некоторых шрифтах — отличить 1 от l будет сложновато (сейчас тоже было не легко, да?)

Имена модулей и пакетов

Имена модулей и пакетов лучше делать покороче и обязательно из строчных букв, но допускается использовать нижнее подчеркивание

Имена классов

Имена классов всегда начинаются с большой буквы. Если слов несколько, то каждая начинается с большой буквы без пробела. «ПримерноВотТакВот» (по-научному это называется ГорбатыйРегистр)

Имена исключений (exceptions)

Исключения именуются по тому же принципу, что и классы. Можно добавить Error в конце имени (если исключение действительно является ошибкой).

Имена функций

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

Аргументы функций и методов

Аналогично функциям пишутся с «маленькой» буквы. Здесь есть небольшое правило. Если имя аргумента конфликтует с зарезервированным в самом питоне ключевым словом, то лучше добавить в конец имени символ подчеркивания, чем исказить написание слова или использовать аббревиатуру. Например,  return_ лучше, чем rtrn. Как вариант — можно подобрать синоним.

Имена методов и переменные экземпляров классов

Используйте тот же стиль, что и для имен функций: имена должны состоять из строчных букв, а слова разделяться символами подчеркивания.

Константы

«Постоянные» переменные должны записываться только заглавными буквами, разделяемыми при необходимости нижним подчеркиванием

# Модули
client
some_module

# Пакеты
scripts

# Классы
ServerAuth

# Исключения
ServerAuthError

# Переменные и аргументы
pc_shutdown

# Имена функций и методов
pc_shutdown
pcShotdown

# Константы
AWESOME_GAME
AVERAGE

 

Автоматизация. Утилита autopep8

Чтобы привести код к стандарту в PEP-8 не обязательно вручную парсить весь написанный код. Естественно, эту процедуру уже давно автоматизировали. Одной из лучших утилит для такой задачи считается проект autopep8. Устанавливается он стандартно, как и любой другой модуль на Python — pip install autopep8

Далее следует настроить утилиту. Идём в File -> Settings -> Tools -> External Tools. И нажимаем добавить

В следующем окне прописываем настройки. Имя — Autopep8, группа — внешние инструменты. В поле program нужно выбрать файл autopep8.exe (нужно выбрать именно исполняемый файл, а не скрипт .py) из каталога, в который он установился. В нашем случае это был такой путь: C:\Users\1\AppData\Local\Programs\Python\Python37-32\Scripts. Обязательно в строку arguments пропишите строку —in-place —aggressive —aggressive $FilePath$. В working directory пропишите $ProjectFileDir$.  Кликните на Advanced Options и в поле Output Filters пропишите $FILE_PATH$\:$LINE$\:$COLUMN$\:.*

После настройки наш автоматический корректор можно использовать. Для этого в IDE откройте ваш файл с кодом. Правой кнопкой мыши вызываем контекстное меню, ищем External Tools и выбираем autopep8

Результат работы. До:

После:

Как проверить код на соответствие?

Для проверки кода на соответствие стандартам PEP-8 существует онлайн-сервис — http://pep8online.com/. Достаточно просто вставить свой код и нажать Check code:

После проверки показываются ошибки, которые необходимо исправить и их описание

В нашем случае большинство ошибок — line too long (XX > 79 characters). Связано это c недопустимой длиной строки (выше мы уже выяснили, что она должна укладываться в 79 символов).

Документация

Документирование проекта — важная часть продукта на всем его жизненном цикле. Для чего вести документацию?

  • Обеспечивает лояльность внешней аудитории и организация сообщества. Когда человек понимает, как, в целом, работает функционал — это мотивирует использовать именно его. Это касается, прежде всего, open source проектов
  • Оперативный траблшутинг. Документация позволит отследить все ошибки в коде в будущем. Логичная структурированная документация — это 50% успеха в поиске багов.
  • Разграничение зон ответственности внутри команды
  • Логичная и структурированная отчетность для заказчика.

Как облегчить себе задачу в документировании?

Стоит отметить несколько подходов, позволяющих упростить ведение технической документации:

  • Автоматические генераторы документации на основе комментариев в коде (о них ниже)
  • Использование шаблонов при написании — единая структура пойдет на пользу как пользователям, её читающим, так и облегчит создание документации разработчикам
  • Подача информации только в простом стиле, без графомании. информация должна раскрывать суть (API, настройка, использование). Два-четыре предложения в абзаце. Четкое донесение мысли
  • Не стоит сразу писать «официальным» языком. Сначала стоит попробовать изложить свои мысли, как видите этот функционал вы сами. Уже затем можно приводить в читаемый вид.
  • Определение аудитории. Сильно поможет упростить задачу ответ на один вопрос: Кто это будет читать? На кого вы ориентируетесь, каков их опыт, скилы, в какой области они работают и т.д.

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

Платформа Sphnix, написанная, кстати, на Python используется по всему миру для автоматизации создания документов для программистов. Её плюсом именно для документации программных продуктов является индексирование заголовков и специального выделения кода (при включении в документ его фрагментов) с соответствующим выделением синтаксиса.

Так же можно использовать различные стили оформления (темы встроены в Sphinx), а так же использовать различные форматы документации «на выходе» — PDF, HTML, LaTex. Из очевидных минусов можно выделить то, что работать придётся в командной строке — GUI не предусмотрен.

Установка стандартная — pip install sphinx

Далее создаем каталог в нашем проекте, пусть это будет documentation. Внутри этой папки запустить CMD с помощью пункта «Открыть окно команд», либо вручную пробраться к ней через команду cd. Там пишем  команду sphinx-quickstart.

Далее будут настройки проекта. Первое — separate source and build directories. Отделение директории source от build — ставим Y («YES» — Да).

Следующая настройка  — Project name, Author name, Release — тут пишем, соответственно, имя проекта, автора и версию релиза

Затем идёт Project Language — здесь можно оставить en, можно поставить ru. Зависит от того, будете ли вы выходить на международный рынок? Мы рекомендуем оставить всё-таки английский язык — чем не повод его подтянуть?

Если всё в порядке, программа напишет нам Finished.

Будут созданы нужные директории в нашей папке documentation

Чтобы sphinx знал, где расположены файлы с доком необходимо в файле сonf.py (он лежит в директории source). Т.е. директорию с кодом добавить в конфиг. В самом файле раскомментируйте строку import sys

Следующую — с sys.path.insert мы тоже раскомментируем, но немного отредактируем. Если мы оставим всё как есть, то берется путь, там где лежит данный файл. Но наши файлы с доком находятся не здесь. Самый простой вариант прописать абсолютный путь до вашего проекта (можете скопировать на Диск С: для удобства и будет что-то вроде C:\myproject). В итоге это будет выглядеть так:

Затем открывайте файл index.rst в вашем IDE и добавляйте именно модулей и классов, которые имеются в директории с исходными кодами. Делается это после параметра Contents:

Записываются модули и классы через двоеточие. Например:

Пункт: members: указывает, что все атрибуты класса будут документированы — нет необходимости прописывать каждую функцию вручную. В конце запустите команду make html (так же как запускали sphinx-quickstart) , чтобы sphnix сформировал документацию с прописанными классами и модулями в HTML-формат