Понятные названия

Названия должны однозначно говорить о том, зачем нужна сущность: переменная, функция или что-то ещё.

Переменные – это сущности, а их названия – это существительные (user.level) или их свойства (user.is_admin). Название должно ясно ответить на вопрос «Что хранит переменная?».

Функции что-то делают с переменными, значит их названия – глаголы (download_report, levelup_user), и они отвечают на вопрос «Что делает функция?». Ответ должен быть полным, исчерпывающим. Например, недопустима ситуация когда def fetch_page(url) делает что-то неожиданное, не предусмотренное названием: выводит в консоль, вызывает exit('Случилась ошибка. Все сломалось') и прочее.

Названия должны быть:

  • понятными: понятно говорить о смысле. Не result, а users_online или json_content.
  • точными: переменная user_online не подходит для хранения списка пользователей. Такое название вводит в заблуждение и провоцирует на ошибки в коде. Корректный вариант — users_online.
  • полными: никаких r для радиуса Земли или i для элемента списка. В первом случае подойдёт earth_radius, а во втором какой-нибудь user или book, в зависимости от того, что в списке. Длинные названия – не проблема, у всех давно есть автокомплит.
  • на английском: никаких kniga или polsovatel. Брр.
  • грамотными: не поленись открыть переводчик и гугл, чтобы подобрать правильный перевод. Неправильный перевод создаёт ощущение неряшливости, а может и смыслу навредить – тогда о читаемости не может быть и речи.
  • уникальными: в Питоне есть встроенные функции, называть переменные их именами нельзя: тогда функция станет недоступна. Среди них есть file, dict, all, str.

Читайте дальше