- Как пишется чистый код?
- 1) Отступы
- 2) Максимальная длина строки
- 3) Пустые строки между функциями и классами
- 4) «Правильный» import модулей
- 5) Пробелы и там, где они не нужны
- Комментарии
- Имена и как их писать
- Имена модулей и пакетов
- Имена классов
- Имена исключений (exceptions)
- Имена функций
- Аргументы функций и методов
- Имена методов и переменные экземпляров классов
- Константы
- Автоматизация. Утилита autopep8
- Как проверить код на соответствие?
- Документация
- Как облегчить себе задачу в документировании?
- Генератор документации Sphinx
- Программирование на максималках:
Правилом хорошего тона в 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-формат
Программирование на максималках:
?️ Как делать авторизацию в Python. Аспекты безопасности
Как вам статья?
620612 285473Some genuinely nice and utilitarian information on this internet web site , likewise I believe the style and style contains superb features. 479520