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

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

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

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

Python
8650