Посібник з іменування змінних
Користь від назви
Програмне забезпечення має бути написане для розуміння людьми, тому імена змінних мають бути відповідними. Люди, які розбирають/читають ваш код, для розширення або виправлення, повинні зрозуміти його. Дуже часто, імена змінних використовують багато місця та ускладнюють розуміння. Навіть інженери діють з хороших спонукань, дуже часто вибирають імена, які в кращому випадку тільки дуже поверхово корисні.
Призначення цього документа допоможе інженерам вибрати хороші імена змінних. Ми будемо спеціально фокусується на рецензуванні коду (code review), тому що саме тут розкривається дуже багато нюансів з поганими іменами змінних. Звичайно, є дуже багато причин для гарного іменування змінних (наприклад, спрощення підтримки коду).
Чому імена змінних?
Основна причина давати змінним осмислені імена - щоб люди могли його зрозуміти. Код, який написаний суто для комп'ютера, швидше за все буде безглуздим.
Приклад автоматично генерованого коду:
Всі інженери можуть сказати, що код вище, надмірно складний для розуміння, а також порушує дві поширені рекомендації:
- Чи не скорочуй;
- Давай осмислені імена.
Можливо несподівано, але ці рекомендації можуть бути контрпродуктивними. Скорочення не завжди погане і буде розглянуто пізніше. А також свідомість термін досить розпливчастий і вимагає пояснень. Деякі інженери думають, що хороші імена завжди повинні бути дуже докладними (наприклад, MultiDictionaryLanguageProcessorOutput ). Інші ж знаходять, що дати осмислені імена вимагає деяких зусиль, і вони здаються десь посередині. Тому дотримання вищезазначених правил призводить до наступногорезультату:
Рецензенти з деякими зусиллями зрозуміють код вище, набагато простіше, ніж перший приклад. Імена змінних читальні та точні. Але вони марні і даремно займають місце, бо:
-
processElements - більшість коду "обробляє" сутності (нарешті, код виконує "процесор"), тому process це сім марних символів які означають не більше ніж "обчислення". elements не набагато кращі. Враховуючи те, що функція щось робить із колекцією, це вже очевидно. Тут навіть помилка в коді, в тому, що ім'я не допомагає читачеві зрозуміти навіщо функція потрібна.
numResults - більшість коду виробляє результат (в результаті), тому як і у випадку з process , Results - сім марних символів. Повне ім'я змінної numResults підказує, що призначена для обмеження кількості виведення, але це досить розпливчасто і вимагає додаткових зусиль у читача.
І все ж таки згадаємо справжнє призначення імен змінних: дати читачеві зрозуміти код, а це вимагає відповіді на наступні питання?
- Якою була мета програміста?
- Що насправді робить код?
Наприклад подивимося як впливають довгі імена на код. Ось переписна функція, яка показує, що читач може отримати від довгих імен:
Змінені імена зробили код гіршим, ніж було в першому прикладі, в якому принаймні імена були короткими. Цей приклад показує, що метапрограміста все ще таємнича, і зараз читач має "сканувати" більше літер. Рецензенти переглядають дуже багато коду, погані імена змінних роблять складну роботу ще складнішою. Як зробити роботу рецензентів менш обтяжливою?
На рецензії (код ревю)
Інший вид навантаження – шаблонність. Часто код, робить щось складне, він написаний кимось іншим, рецензент часто перемикається на свій код, він переглядає дуже багато різного коду, щодня, і міг робити це протягом багатьох років. Знаючи все це, рецензенти щосили намагатися зберегти фокус під час рецензування. Таким чином, кожна марна буква випаровує ефективність рецензування. Немає проблеми розібрати невеликий приклад незрозумілого коду. Рецензенти можуть розібратися практично у будь-якому коді, якщо є достатньо часу та сил (ймовірно з питаннями до програміста). Але вони не можуть собі цього дозволити робити щоразу знову і знову, рік у рік. Це сміття через 1000 порізів.
Гарний приклад
Щоб показати рецензенту свої наміри з мінімальним кількість літер, програміст міг переписати код так:
Давайте розглянемо зміну імені кожної змінної у тому щоб побачити як вони допомагають робити код легше і зрозуміліше:
- printFirstNPositive - на відміну від processElements , тепер стало ясно що програміст хотів щоб ця функція зробила (і з'являється шанс помітити помилку)
- n - очевидно, враховуючи назву функції, немає необхідності для більш складної назви
c - колекція не додає розумового навантаження, до того ж коротше на 9 букв для зменшення навантаження на читача. Так як функція коротка і задіяна тільки одна колекція, то і легко запам'ятати що це колекція цілихчисел.
Так само зараз можна побачити дві помилки в коді. У першій версії коду було не зрозуміло, що програміст хоче відобразити тільки позитивні числа. Читач тепер може помітити, що тут помилка, тому що нуль не позитивне число (бо n має бути більше нуля, а не більш-рівно). (Так само тут мають бути модульні тести). І навіть більше, оскільки перший аргумент тепер називається maxToPrint (на відміну від, скажімо, maxToConsider ), тепер видно, що функція не завжди надрукує достатньо елементів у випадку, якщо в колекції є негативні числа. Написання правильної функції залишається як вправу читачеві.
Принципи іменування (якщо звичайно немає кращих)
Для того щоб перейняться принципами, ось кілька рекомендацій як їх використовувати в коді.
Не додавайте в назву інформацію про тип
(прим. пров. має сенс лише у типизованих мовах)
Наступною поширеною помилкою є додавання Str або String до імені або включати тип колекції в ім'я. Ось кілька рекомендацій: