Чи є привід для коротких імен змінних?

Це стало великим розладом із кодовою базою, над якою я зараз працюю; багато наших імен змінних є короткими та неописними. Я єдиний розробник, що залишився в проекті, і немає документації щодо того, що більшість з них робить, тому мені доводиться витрачати додатковий час на пошук того, що вони представляють.

Наприклад, я читав якийсь код, який оновлює визначення оптичної поверхні. Змінні, встановлені на початку, були наступними:

double dR, dCV, dK, dDin, dDout, dRin, dRout
dR = Convert.ToDouble(_tblAsphere.Rows[0].ItemArray.GetValue(1));
dCV = convert.ToDouble(_tblAsphere.Rows[1].ItemArray.GetValue(1));
... and so on

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

dR = radius
dCV = curvature
dK = conic constant
dDin = inner aperture
dDout = outer aperture
dRin = inner radius
dRout = outer radius

Я перейменував їх по суті на те, що у мене є. Це подовжує деякі лінії, але я відчуваю, що це справедлива торгівля. Однак ця схема імен використовується в багатьох кодах. Я не впевнений, чи це артефакт від розробників, які дізналися, працюючи зі старими системами, чи є в цьому глибша причина. Чи є вагомі підстави називати змінні таким чином, чи я виправдовуюсь оновленням їх до більш описових імен, коли я стикаюся з ними?

Здається, що ці назви змінних засновані на абревіатурах, які ви очікуєте знайти в підручнику з фізики, працюючи з різними проблемами оптики. Це одна з ситуацій, коли короткі імена змінних часто є кращими, ніж довші імена змінних. Якщо у вас є фізики (або люди, які звикли опрацьовувати рівняння вручну), які звикли використовувати загальні абревіатури, такі як Rin, Rout, і т. Д., Код буде набагато зрозумілішим із цими абревіатурами, ніж з більш довгими назвами змінних. Це також значно полегшує порівняння формул з паперів та підручників з кодом, щоб переконатися, що код насправді робить обчислення належним чином.

Кожен, хто знайомий з оптикою, негайно розпізнає щось на зразок Ріна як внутрішній радіус (у фізичному документі цей inвигляд буде відображатися як підпис), Rout як зовнішній радіус тощо. Хоча вони майже напевно зможуть подумки щось перекласти як innerRadiusі більш звичну номенклатуру, це зробило б код менш зрозумілим для цієї людини. Складніше було б помітити випадки, коли знайома формула була закодована неправильно, і це ускладнить переклад рівнянь у коді до та з рівнянь, які вони знайдуть у статті чи підручнику.

Якщо ви єдина людина, яка коли-небудь переглядає цей код, вам ніколи не потрібно перекладати між кодом і стандартним рівнянням оптики, і навряд чи фізику коли-небудь потрібно буде шукати код у майбутньому, можливо, це і є має сенс рефактор, оскільки користь від скорочень більше не перевершує вартість. Якби це була нова розробка, однак, майже напевно було б сенс використовувати ті самі скорочення в коді, які ви знайдете в літературі.

Змінні з коротким терміном життя повинні бути названі незабаром. Як приклад, ви не пишете for(int arrayCounter = 0; arrayCounter < 10; arrayCounter++) { .... Натомість ви використовуєте for(int i ....

Загалом, можна сказати, що чим коротше область змінної, тим коротше має бути назва. Цифрові лічильники часто - це лише одні літери, скажімо i, jта k. Локальні змінні - це щось на зразок baseабо fromта to. Скажімо, глобальні змінні дещо детальніше, наприклад EntityTablePointer.

Можливо, таке правило не дотримується з кодовою базою, з якою ви працюєте. Це хороший привід для того, щоб зробити якийсь рефакторинг!

Проблема з кодом - це не короткі назви, а скоріше відсутність коментаря, який би пояснював абревіатури, або вказував на деякі корисні матеріали про формули, з яких походять змінні.

Код просто передбачає знайомство з проблемною областю.

Це добре, оскільки знайомство з проблемними доменами, ймовірно, потрібно для розуміння та підтримання коду, особливо в ролі того, хто його "володіє", тож вам потрібно набути знайомства, а не обходити подовження імен.

Але було б добре, якби код дав якісь підказки, щоб вони послужили трамплінами. Навіть доменний експерт міг забути, що dKце конічна константа. Додавання трохи "шпаргалки" до блоку коментарів не завадить.

Для певних змінних, які добре відомі в проблемній області - як і у випадку, який ви маєте тут - необґрунтовані короткі назви змінних. Якщо я працюю над грою, я хочу, щоб мої ігрові організації мали змінні позицій, xа yне horizontalPositionі verticalPosition. Аналогічним чином лічильники петлі , які не мають ніякої семантики крім індексації, я очікую побачити i, j, k.

Запис до "Чистого коду":

Імена змінних повинні:

• Будьте розкриваючи намір
• Уникайте дезінформації
• Робіть змістовні розрізнення
• Бути вимовляльним
• Будьте в пошуку

Виняток становлять прислів’я, які i,j,k,m,nвикористовуються для циклів.

Імена змінної, на яку ви, по праву, нарікаєте, не роблять нічого з перерахованого. Ці імена - невірні імена.

Крім того, як кожен метод повинен бути коротким , використовуючи префікси, які вказують, що сфера чи тип більше не використовуються.

Ці назви краще:

radius
curvature
conicConstant
innerAperture
outerAperture
innerRadius
outerRadius

Коментолог каже, що це було б занадто складно з довгими назвами змінних:

Короткі імена змінних також не спрощують:

fnZR = (r^2/fnR(1+Math.sqrt((1+k) * (r^2/R^2)))) + a[1]*r^2 + a[1]*r^4 + a[1]*r^6 ...;

Відповідь - це довгі імена та проміжні результати, поки ви цього не отримаєте в кінці:

thisNiceThing =  ( thisOKThing / thisGreatThing ) + thisAwsomeThing;

Є дві вагомі причини не перейменовувати змінні в застарілий код.

(1) якщо ви не використовуєте автоматизований інструмент рефакторингу, можливість введення помилок висока. Отже, "якщо це не зламано, не виправляйте"

(2) ви зробите порівняння поточних версій з попередніми версіями, щоб побачити, що змінилося, неможливо. Це ускладнить подальше обслуговування коду.

Чи є вагомі підстави називати змінні таким чином, чи я виправдовуюсь оновленням їх до більш описових імен, коли я стикаюся з ними?

Причина використовувати менші імена - якщо оригінальний програміст їм легше працювати. Імовірно, вони мають право визнати, що це так, і право не мати тих самих особистих уподобань, як у вас. Особисто я знайшов би ...

dDin better than dDinnerAperture
dDout better than dDouterAperture

... якби я використовував їх у довгих складних обчисленнях. Чим менший математичний вираз, тим частіше простіше побачити всю справу відразу. Хоча якби це було так, вони могли б бути кращими як dIn та dOut, тому не було повторюваного D, який міг би призвести до простого друку.

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

Як правило, я вважаю, що правилом для цього є те, що ви можете використовувати надзвичайно короткі імена змінних, де ви знаєте, що люди, "кваліфіковані у галузі техніки" вашого конкретного коду, відразу зрозуміють посилання на ім'я змінної. (У будь-якому випадку ви завжди маєте коментарі за винятком цього випадку), і що локалізоване використання змінних можна легко визначити, виходячи з контексту їх використання.

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

Щоб використати приклад із реального світу, нещодавно я створював клас Javascript, який займав би широту, і розповідав вам кількість сонячного світла, якого ви очікували в дану дату.

Для створення цього класу Sundial я згадував, можливо, півдесятка ресурсів, альманах Astronomy та фрагменти з інших мов (PHP, Java, C тощо).

Практично у всьому з них вони використовували подібні однакові абревіатури, які на обличчі не означають абсолютно нічого.

K, T, EPS, deltaPsi, eot, LM,RA

Однак якщо ти маєш знання фізики, ти можеш зрозуміти, якими вони були. Я б не очікував, що хтось торкнеться цього коду, тож навіщо використовувати імена змінних багатослівних?

julianTime, nutationOfEclipticalLongitudeExpressedInDegrees, equationOfTime, longitudeMean, rightAscension.

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

Там абсолютно є; часто разів коротка назва змінної - це все, що потрібно.

У моєму випадку я роблю навігацію на точковій точці у своєму старшому класі робототехніки, і ми програмуємо наших роботів у KISS-C. Нам потрібні змінні для поточних та кінцевих координат (x, y), (x, y) відстаней, поточних та пунктів призначення, а також кутів повороту.

Тим більше, що стосується координат x і y, довге ім'я змінної зовсім непотрібне, а таких імен, як xC (поточний x), yD (призначення y) та pD (phi призначення), достатньо і їх найлегше зрозуміти в цьому випадку.

Ви можете стверджувати, що це не «описові імена змінних», як диктував би протокол програміста, але оскільки імена засновані на простому коді (d = призначення, c = поточний), на початку дуже простий коментар - це все опис вони вимагають.

Чи є вагомі підстави називати змінні таким чином, чи я виправдовуюсь оновленням їх до більш описових імен, коли я стикаюся з ними?

Зазвичай складні алгоритми реалізуються в matlab (або подібній мові). Я бачив, що люди просто переймають ім'я змінних. Таким чином, порівняти реалізацію досить просто.

Усі інші відповіді майже правильні. Ці абревіатури можна знайти з математики та фізики, за винятком того, що вони не починаються з d(як у вашому прикладі). Змінні, що починаються з d, зазвичай називають для відображення диференціації .

Усі звичайні посібники з кодування наказують не називати змінних першою буквою, що представляє тип (як у вашому випадку), оскільки так легко переглядати код у всіх сучасних IDE.

Я можу подумати, що причина змінних імен може бути досить короткою.

Короткі назви легко читати, використовуючи коротший простір очей, отже, короткий проміжок уваги.

Наприклад, коли я звикаю до того, що svdb означає "зберегти в базі даних", швидкість сканування вихідного коду покращується, оскільки мені потрібно швидко сканувати 4 символи замість того, щоб читати SaveToDatabase (14 символів, все погіршується для більш складних імен операцій). Я кажу: "сканування" не "читання", тому що це займає велику частину аналізу вихідного коду.

При скануванні через велику кількість вихідного коду це може забезпечити хороші показники продуктивності.

Крім того, він просто допомагає лінивому програмісту набрати ці короткі імена під час написання коду.

Звичайно, очікується, що всі ці "стенограми" будуть перелічені в якомусь стандартному місці у вихідному коді.

Сформулювати те, що сказав @zxcdw, дещо по-іншому, і детально розглянути це з точки зору підходу:

Функції повинні бути чистими , короткими та досконалою інкапсуляцією деякої функціональності: логіка чорного поля , незалежно від того, чи не сиділа вона нетронутою протягом 40 років, буде продовжувати виконувати роботу, для якої вона була розроблена, оскільки її інтерфейс (увімкнений і вийшов) звук, навіть якщо ви нічого не знаєте з його внутрішніх справ.

Це такий тип коду, який ви хочете написати: це код, який триває і простий у портуванні.

Де потрібно, складіть функції з інших (вбудованих) функцій викликів , щоб зберегти код тонкозернистим.

Тепер, з відповідним описовим іменем функції (при необхідності докладно!), Ми мінімізуємо будь-який шанс неправильного тлумачення цих скорочених імен змінних, оскільки область застосування настільки мала.

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

Немає вагомих причин не використовувати описову назву. Це допоможе вам і всім, хто працює / буде працювати над проектом. Ну насправді існує одне дійсне використання для коротких імен: циклічні лічильники.

Звичайно, саме для цього // коментарі?

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

Для інтерфейсів (наприклад, підписи методів, підписи функцій) я схильний вирішувати це шляхом анотування декларацій параметрів. Для C / C ++ це прикрашає .h файл, а також код реалізації.

Я роблю те саме для оголошень змінних, коли знання використання змінної не очевидно в контексті та в іменуванні. (Це стосується мов, які також не мають сильного введення тексту.)

Є багато речей, які ми не хочемо засмічувати ім'я змінної. Чи є кут у радіанах чи градусах, чи є деяка допуск на точність чи дальність і т.д. Інформація може дати цінні твердження про характеристики, з якими слід правильно поводитися.

Я не релігійний з цього приводу. Мене просто цікавить ясність і впевненість у тому, що я зараз, що це наступного разу, коли мій забуваючий власний власник відвідує код. І кожен, хто дивиться через моє плече, має те, що йому потрібно знати, щоб побачити, де щось вимкнено, що важливо (остання важлива для правильного обслуговування).

Чи є привід для надмірно коротких імен змінних?

По-перше: називання змінної для енергії e під час обчислення формул, таких як E = MC2, НЕ є надмірно коротким іменуванням. Використання символів як аргументу для коротких імен недійсне

Це питання було досить цікавим для мене, і я можу придумати лише одне виправдання, а це гроші.

Скажімо, наприклад, ви підключаєте javascript для клієнта, який знає, що файл потрібно завантажувати багато разів на секунду. Це було б дешевше і зробить досвід користувачів кращим, якби файл (у кількості байтів) був якомога меншим.

(Тільки для того, щоб приклад "реалістичний", вам не було дозволено використовувати інструмент minifier. Чому? Проблеми безпеки, жодних зовнішніх інструментів не можна торкатися бази коду.)

Я зауважую, що в інших відповідях не згадується використання угорської нотації. Це ортогонально для тривалої дискусії, але стосується схем іменування загалом.

double dR, dCV, dK, dDin, dDout, dRin, dRout

"D" на початку всіх цих змінних мається на увазі, що вони подвійні; але мова все одно це виконує. Незважаючи на лаконічність цих імен, вони до 50% зайві !

Якщо ми будемо використовувати конвенцію про іменування для зменшення помилок, нам набагато краще використовувати інформацію про кодування, яка не перевіряється мовою. Наприклад, жодна мова не скаржитьсяdK + dR на вищезазначений код, навіть якщо додати безрозмірне число до довжини безглуздо.

Хороший спосіб запобігти таким помилкам - використовувати більш сильні типи; однак, якщо ми будемо використовувати парні, то більш прийнятною може бути схема іменування:

// Dimensions:
// l  = length
// rl = reciprocal length
double lR, rlCV, K, lDin, lDout, lRin, lRout

Мова все одно дозволить нам писати K + lR , але тепер імена дають нам натяк на те, що це може бути неправильним.

Це різниця між системою Угорська (загалом погана) та Угорською програмами (можливо, хорошою)

http://en.wikipedia.org/wiki/Хунгарська_нотація

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