Продвинутая логика именования в Python

Разобрали на примерах, как и почему лучше называть различные объекты в Python.

Если вы уже практикуете программирование на Python и испытываете проблемы с отложенным чтением (как и большинство кодеров), то ваш навык именования может стать зоной роста.

Комментировать код зачастую не хочется. Во-первых, на это уходит много времени и сил. Во-вторых, неизвестно, пригодятся ли это вообще. Ведь программа может оказаться временной, и ей перестанут пользоваться через пару дней. Или сеньор удалит половину строк — вместе с теми самыми комментариями.

В такой ситуации немалую пользу принесет навык именования объектов кода.

Как назвать переменную — вопрос сложный и болезненный. Его обсуждают авторы на Хабре, за плохие попытки осуждают на Stack Overflow. Ситуацию высмеивают в мемах. Если назвать переменную неправильно — или просто странно — люди, которым впоследствии придётся читать и рефакторить ваш код, запутаются. А после придут узнавать, что вы имели в виду под uber_magic_cat и где расширенные комментарии.

Чтобы таких ситуаций не было, и ни вы, ни команда не тратили своё время и ресурсы, предлагаю разобраться в теме и научиться правильно называть объекты.

Сперва вспомним базу: PEP 8

PEP (Python Enhancement Proposal) – руководство по улучшению кода, описывает рекомендации и стандарты, которые делают код более читаемым и понятным. Вот его основные принципы.

Отступы и пробелы

Используйте четыре пробела для каждого уровня отступа. Не используйте табуляцию;
Избегайте пробелов в конце строки;
Добавляйте пустые строки между функциями и классами — и по обе стороны от операторов.

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

Ограничивайте строки кода до 79 символов (это оптимальная длина для среднестатистического экрана);
Если выражение длинное, делайте перенос как в примере ниже:

			payload = {'dimensions': 'ym:s:refererPath', 
           'date1': date1,  
           'date2': date2,  
           'filters': "", 
           'accuracy': 'full', 
           'pretty': True, 
           'limit': 70000
}

Импорты

Группируйте импорты в следующем порядке: стандартные, сторонние библиотеки, самописные модули. Разделяйте группы пустыми строками;
Импортируйте только необходимые компоненты.

Пробелы до и после операторов

Используйте пробелы до, после операторов (= + — * / и проч.) и после запятых;
Не добавляйте лишних пробелов: они могут ухудшить читаемость кода.

Имена переменных и функций

Имена должны легко читаться, для разделения слов используйте нижние подчеркивания (например, record_count, calculate_total);
Для констант используйте ЗАГЛАВНЫЕ_БУКВЫ_С_ПОДЧЕРКИВАНИЯМИ;
Не начинайте название с цифры;
Избегайте зарезервированных создателями ЯП слов (list, dict и так далее).

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

Используйте docstrings для документирования модулей, функций, классов и методов.
Документируйте параметры функций, возвращаемые значения и возможные исключения.

Логические блоки

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

			def foo(s):
    return s == "hello"

Лучше так:

			def foo(s):
    c_string = "hello" # Выносим строку-константу в хорошо заметную переменную
    return s == c_string

Зайдем немного глубже

Теперь хочу обратить ваше внимание на пятый пункт — «Имена переменных и функций». Вы когда-нибудь задумывались, какими частями речи именовать тот или иной объект? Классу лучше быть существительным, функции – сказуемым, это, кажется логичным. Но как быть с остальными объектами?

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

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

Переменные

Но переменных много, правил именования — тоже. И базовая программа не охватывает всё. Поэтому делюсь несколькими принципами, которые я использую в повседневной работе:

Используйте аббревиатуры. Так в моём боте выглядит переменная, содержащая идентификатор пользователя Telegram:

			tg_id = message.chat.id

Оставляйте неизменными названия переменных, которые устоялись в документации. Порой проще дописать комментарий об объекте и найти подсказку в Stack Overflow, чем получить понятное название, содержимое которого спустя месяц не отладить:

			# Класс для временного хранения всех реплик переписки бота на aiogram
storage = MemoryStorage()

Опускайте гласные в существительных. В рунете этой практике только предстоит устояться. А зря. Даже частичное опущение подойдет:

			instrument → instrmnt

Функции

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

			def level_count(): # Рассчитываем уровень игрока   ...

Столбцы таблиц и столбцов

С этим сталкиваюсь на практике практически каждый день. Вот основные принципы, которые я определила (думаю, во многом рекомендации у специалистов с опытом совпадут):

По умолчанию именуйте столбцы по-английски. Большая часть библиотек сегодня поддерживает обращение через квадратные скобки (для случаев, когда в названии не латиница). Но если название станет аргументом, передаваемым через командную строку, то придётся запоминать, как именно передавать кириллицу:

			python3 sample_script.py `столбец`

Если решили именовать столбец по-русски, старайтесь использовать небольшое название (до 20 символов): такое при многократном обращении к столбцу не потребуется долго набирать:

			df['технология']

Файлы

Если речь идет о временном файле, который вы изучите сразу после исполнения и удалите, достаточно назвать его как объект:

			df.to_csv('df.csv')

Однако если речь идет о регулярном использовании, лучше «вложиться»:

			new_users_google_analytics.py

Гуглите и используйте аббревиатуры. К примеру, датафрейм о пациентах, прошедший Предварительную обработку данных (Exploratory Data Analysis) и выгруженный в файл, можно назвать ‘patients_eda.csv’.
Пишите в README пояснения к скриптам. Документация репозитория выручит, если придумать хорошее название не удастся.

Заключение

Работа с именованием переменных постепенно становится проще. Уже сегодня можно спросить у ИИ-расширения для VSCode Codeium, что делает тот или иной объект — и отталкиваться от ответа. Но порой ответы бывают малополезными: