Продвинутая логика именования в 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, что делает тот или иной объект — и отталкиваться от ответа. Но порой ответы бывают малополезными:

Так что пока приходится самим искать идеальные названия. Хотелось бы верить, ситуация в будущем изменится.

Встречали странные имена в коде? Поделитесь в комментариях.