Аватарка пользователя Елена Капаца
Елена Капаца

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

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

7979

Если вы уже практикуете программирование на 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
7979
Что думаете?
7 комментариев
Сначала интересные
Аватар пользователя Anna
Название функции лучше ВСЕГДА начинать с глагола. В примере в статье функция level_count не прошла бы моё  Code Review. Она должна называться count_level.
Аватар пользователя Никита Большаков
Anna, Опять же ваш ревью. Да, я и сам считаю это правильным подходом, но если вы вливаетесь в проект или в новую команду, у них могут быть свои устоявшиеся правила, под которые придется подстраиваться
Аватар пользователя Никита Большаков
Anna, Сам считаю такой подход верным. Но опять же, это просто одна из точек зрений. Сам лично участвовал в проектах, в которых устоявшиеся правила твердили об обратном. Нужно всегда оставаться гибким и подстраиваться под общие стандарты
Аватар пользователя Ingeniosus
забыли важное: leading underscope: 
_local_var
_LOCAL_CONST
_NoImportingClass
...
это очень важно в чтении, особенно создании классов, методов класса и приватных методах. 
Плюс, интерактивный интерпретатор при подсказках будет игнорировать все это.
Аватар пользователя ezdiumno ru
Многие из этих советов полезны и для других языков. Спасибо.
Показать все комментарии
Курсы
набор еще идетонлайн7590₽
набор еще идетонлайнбесплатно
набор еще идетонлайнбесплатно
набор еще идетонлайн2790₽
Все курсы