Нейминг в коде: 5 правил, которые спасают проект

27 сентября 2024 Uncategorised, Инженерия

В разработке мы любим сложные темы: SOLID, DRY, паттерны проектирования. А нейминг в коде - одна из самых простых вещей - тихо решает, будет ли код читаемым через год. Эта статья о том, почему имена важны и как заставить их работать на вас.

Цена плохого имени

Код с плохим неймингом - лабиринт без указателей. Он замедляет всех и повышает вероятность ошибок. Когда вы возвращаетесь к такому коду через месяцы, обычно есть три сценария:

Полный рефакторинг - больше работы и больше риска новых ошибок.
Точечные правки, которые делают код ещё запутаннее.
Поверхностные изменения без анализа, которые пропускают важные детали.

Что даёт хороший нейминг в коде

Код понимается быстрее.
Меньше времени на рефакторинг и отладку.
Проще онбординг новых разработчиков.
Лучше коммуникация в команде.
Меньше потребности в избыточной документации.

Читаемость: от calc к предложению

Этот код работает, но его назначение не очевидно с первого взгляда:

def calc(n1, n2, op):
    if op == '+':
        return n1 + n2
    elif op == '-':
        return n1 - n2
    elif op == '*':
        return n1 * n2
    elif op == '/':
        return n1 / n2 if n2 != 0 else "Error: Division by zero"
    return "Error: Invalid operation"

Те же действия, но имена объясняют себя:

def perform_arithmetic_operation(first_number, second_number, operation):
    if operation == '+':
        return first_number + second_number
    elif operation == '-':
        return first_number - second_number
    elif operation == '*':
        return first_number * second_number
    elif operation == '/':
        return first_number / second_number if second_number != 0 else "Error: Division by zero"
    return "Error: Invalid operation"

Функция говорит, что делает, без единого комментария.

Предотвращение ошибок: хук должен выглядеть как хук

В React префикс use - это контракт. Переименуйте функцию, и правило станет заметным:

function getData(url) {
  const [data, setData] = React.useState(null);
  React.useEffect(() => {
    fetch(url).then(r => r.json()).then(setData);
  }, [url]);
  return data;
}

getData на самом деле хук, но имя это скрывает. Вызов внутри обработчика клика ломает правила хуков. Исправление - одно слово:

function useDataFetching(url) {
  const [data, setData] = React.useState(null);
  React.useEffect(() => {
    fetch(url).then(r => r.json()).then(setData);
  }, [url]);
  return data;
}

Теперь очевидно, что useDataFetching вызывается на верхнем уровне компонента.

Поиск по коду

В большом проекте такие имена невозможно найти:

function process(data) { /* ... */ }
function handle(info) { /* ... */ }
function manage(userData) { /* ... */ }

Описательные имена возвращают поиску смысл:

function processUserRegistration(userData) { /* ... */ }
function handlePasswordReset(userCredentials) { /* ... */ }
function manageUserPreferences(userSettings) { /* ... */ }

Заключение

Один источник, который стоит держать под рукой: обзор соглашений об именовании.

Хороший нейминг - не косметика. Это инструмент для кода, который понятен, поддерживаем и дешево меняется. Потратьте минуту на имя сегодня - и сэкономьте час себе и коллегам в следующем квартале.

Вопросы про переименование

Переименовывать старый код? Переименовывайте, когда его трогаете. Глобальный рефакторинг без тестов - отдельный проект.

Короткие имена плохие? Только когда скрывают смысл. Индекс цикла нормален, сущность с именем data нет.

А сокращения? Одно значение на проект. Если usr в одном файле пользователь, а в другом использование, имя сломано.

Правило нейминга в коде для ревью

Правило простое: если имя требует комментария, имя плохое. PEP 8 даёт базовый уровень для Python, дальше начинается вкус команды. Нейминг в коде - единственная документация, которую читают всегда.

Имена читают чаще, чем пишут, поэтому лишняя минута окупается.

Ещё по теме: Архитектура ПО: шесть паттернов и как выбрать и Глубина SQL: один запрос вместо бэкенд-сервиса.

Важность правильного нейминга в коде