Если вы уже практикуете программирование на Python и испытываете проблемы с отложенным чтением (как и большинство кодеров), то ваш навык именования может стать зоной роста.
Комментировать код зачастую не хочется. Во-первых, на это уходит много времени и сил. Во-вторых, неизвестно, пригодятся ли это вообще. Ведь программа может оказаться временной, и ей перестанут пользоваться через пару дней. Или сеньор удалит половину строк — вместе с теми самыми комментариями.
В такой ситуации немалую пользу принесет навык именования объектов кода.
Как назвать переменную — вопрос сложный и болезненный. Его обсуждают авторы на Хабре, за плохие попытки осуждают на Stack Overflow. Ситуацию высмеивают в мемах. Если назвать переменную неправильно — или просто странно — люди, которым впоследствии придётся читать и рефакторить ваш код, запутаются. А после придут узнавать, что вы имели в виду под uber_magic_cat и где расширенные комментарии.
Чтобы таких ситуаций не было, и ни вы, ни команда не тратили своё время и ресурсы, предлагаю разобраться в теме и научиться правильно называть объекты.
PEP (Python Enhancement Proposal) – руководство по улучшению кода, описывает рекомендации и стандарты, которые делают код более читаемым и понятным. Вот его основные принципы.
payload = {‘dimensions’: ‘ym:s:refererPath’, ‘date1’: date1, ‘date2’: date2, ‘filters’: «», ‘accuracy’: ‘full’, ‘pretty’: True, ‘limit’: 70000 }
def foo(s): return s == «hello»
Лучше так:
def foo(s): c_string = «hello» # Выносим строку-константу в хорошо заметную переменную return s == c_string
Теперь хочу обратить ваше внимание на пятый пункт — «Имена переменных и функций». Вы когда-нибудь задумывались, какими частями речи именовать тот или иной объект? Классу лучше быть существительным, функции – сказуемым, это, кажется логичным. Но как быть с остальными объектами?
Давайте пройдемся по часто используемым типам объектов и посмотрим, как лучше поступить с их именованием.
В качестве примеров буду приводить части своего кода: я обеспечиваю полный жизненный цикл данных из разных ботов: выгрузка, обработка, подгрузка в хранилище и вёрстка обновляемых отчётов. Так что специфику других профессий глубоко не затрагиваю.
Но переменных много, правил именования — тоже. И базовая программа не охватывает всё. Поэтому делюсь несколькими принципами, которые я использую в повседневной работе:
tg_id = message.chat.id
# Класс для временного хранения всех реплик переписки бота на aiogram storage = MemoryStorage()
instrument → instrmnt
В название функции часто добавляются сказуемое (глагол или причастие). Однако в моей практике для разграничения похожих функций удобнее приписывать еще и дополнение:
def level_count(): # Рассчитываем уровень игрока …
С этим сталкиваюсь на практике практически каждый день. Вот основные принципы, которые я определила (думаю, во многом рекомендации у специалистов с опытом совпадут):
python3 sample_script.py `столбец`
df[‘технология’]
Если речь идет о временном файле, который вы изучите сразу после исполнения и удалите, достаточно назвать его как объект:
df.to_csv(‘df.csv’)
Однако если речь идет о регулярном использовании, лучше «вложиться»:
new_users_google_analytics.py
Работа с именованием переменных постепенно становится проще. Уже сегодня можно спросить у ИИ-расширения для VSCode Codeium, что делает тот или иной объект — и отталкиваться от ответа. Но порой ответы бывают малополезными:
Так что пока приходится самим искать идеальные названия. Хотелось бы верить, ситуация в будущем изменится.
Встречали странные имена в коде? Поделитесь в комментариях.
Разобрали на примерах, как и почему лучше называть различные объекты в 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.
