Чистый код на 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

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

Комментарии

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

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

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

Правильно именовать переменные или функции — тоже работа программиста. Здесь есть свои правила хорошего тона — например, нельзя использовать латинские буквы 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-формат

Как вам статья?