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

У розробці ми любимо складні теми: SOLID, DRY, патерни проєктування. А неймінг у коді - одна з найпростіших речей - тихо вирішує, чи буде код читабельним через рік. Ця стаття про те, чому імена важливі й як змусити їх працювати на вас.

Ціна поганого імені

Код із поганим неймінгом - лабіринт без покажчиків. Він сповільнює всіх і підвищує ймовірність помилок. Коли ви повертаєтеся до такого коду через місяці, зазвичай є три сценарії:

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

Що дає хороший неймінг у коді

1. Код розуміється швидше.
2. Менше часу на рефакторинг і налагодження.
3. Простіший онбординг нових розробників.
4. Краща комунікація в команді.
5. Менша потреба в надлишковій документації.

Читабельність: від 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: один запит замість бекенд-сервісу.