Як би це назвати: принципи хорошого іменування в базі коду

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

Називайте об'єкти своїми іменами

Найпростіша ідея — назвати об'єкти так, як їх вже називають користувачі вашої системи. Наприклад, можна з великою часткою впевненості сказати, що десь усередині бази коду «Твіттера» є сутність з назвою Tweet. Цей принцип звучить просто, однак вимагає правильного підходу до архітектури. Якщо ви проектуєте правильно, то всередині бази коду в основному ті об'єкти і сутності, якими оперує кінцевий користувач. І в багатьох випадках всі вони вже мають сформовані назви.

Ця стратегія діє при Object Oriented Design (OOD) підході. Хороший OOD має максимальну кількість класів, якими може оперувати і які може зрозуміти кінцевий користувач, і мінімальна кількість класів, які він не може бачити. Назви всіх об'єктів, які бачить кінцевий користувач, повинні диктуватися їм самим.

Наприклад, уявімо, що всередині вашого проекту є поняття «Article» і «Email». У обох є заголовок — header. Але для статті користувачі назвуть його «Title», а для імейла — «Subject». Принцип слідування за користувачем вимагає дати цих заголовків різні назви на рівні коду, що спростить комунікацію і зменшить труднощі у спілкуванні, які опишу нижче.

Слід зауважити, що це не єдиний принцип іменування. Може бути кілька причин, по яких ви можете назвати об'єкти не своїми іменами всередині коду. Розповім про них нижче.

Також є проблема Legacy: у міру розвитку проекту назви змінюються за різних причин. Однак перейменувати об'єкти в коді не завжди можливо. Іноді доводиться створювати таблиці термінів, в яких для кожного актуального терміна буде не тільки опис, але і список його старих Legacy назв.

Не використовуйте схожі назви, тільки щоб спростити

Якщо ви изобретаете нове поняття, про яке ваші користувачі ще не чули, постарайтеся дати йому ім'я, яке ще не використано. Людина завжди прагне до спрощень. Тому ми часто використовуємо одна назва для різних речей. Наприклад, «Коса». Ми просто вже всі до цього звикли. Однак якщо ви назвете об'єкти однаковими іменами в своєму софті, вам доведеться пояснювати вашим користувачам або розробникам, що це різні об'єкти.

Ось приклад з життя. Уявімо, що в системі користувачам доступні 2 дії: «Subscribe to newsletter» і «Unsubscribe from all email notifications». Оскільки ми маємо звичай все спрощувати, комусь може здатися, що ці дві дії протилежні один одному, так як «unsubscribe» протилежно «subscribe». Але це не так — на практиці це можуть бути незалежні дії: наприклад, ви можете бути підписані на розсилку і не підписані на інші сповіщення. Або, наприклад, ви не можете бути підписані на розсилку, якщо відписалися від всіх сповіщень.

Для того щоб уникнути «автоматичного спрощення», ви можете назвати ці дії по різному: «Opt in for newsletter» і «Unsubscribe from all email notification». Таким чином, помилка стане менш вірогідною, оскільки «opt in» прямо протилежно «unsubscribe». Ідея в тому, щоб закріпити «opt in» за «newsletter subscription» і «unsubscribe» — для «email notifications».

В щоденному спілкуванні люди говорять дуже швидко, скорочуючи непотрібні слова. Це означає, що багато дії будуть використані без опису об'єкта дії. Наприклад: «How many subscribed people do we have?» буде сприйматися неоднозначно, якщо «subscribe» буде асоціюватися і з «newsletter», і з «email notifications».

Різними поняттями давайте різні назви

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

Але є проблеми унікальності імен, яких можна було уникнути. Уявімо, що в проекті є поняття «WebPageSnapshot» і «ServerSnaption». Коли члени команди розмовляють швидко, то швидше за все будуть використовувати слово «Snapshot» для обох понять. Це може призвести до проблем розуміння. Фраза «I made a patch that touches a snapshot source code, please take a look» неточно визначає, куди саме потрібно дивитися. Подібні фрази майже гарантовано будуть вести до втрати часу, тому що співрозмовники будуть вважати, що розуміють один одного, а насправді — не зовсім. Або автор, або слухач в даному випадку можуть взагалі не знати про те, що в системі є 2 різних види Snapshot, і для них може бути навіть неочевидна неточність висловлювання.

Звідси випливає правило: використовуйте уточнюючі слова, щоб розділяти поняття, тільки якщо ці поняття мають одне і те ж значення на якомусь рівні абстракції. Наприклад, «VideoFile» і «ImageFile» — обидва просто «File» на більш узагальненому рівні. Іншими словами, VideoFile і ImageFile мають загальну поведінку і код, який їх обробляє або реалізує. Якщо такої спільності немає — потрібно дати поняттями абсолютно різні імена.

Переконайтеся, що скорочені версії назв зручні

Використання однакових уточнюючих слів, з іншого боку, може бути гарною ідеєю. Давайте розглянемо бізнес-правило: «„Affiliate Member“ can participate in „Affilicate Campaign“». При таких назвах не буде ніякої плутанини. Без уточнень фраза залишається зрозумілою: «This member has joined the campaign 2 days ago».

Навпаки, бізнес-правило «„Affiliate Member“ can participate in „Campaign Affiliate“» може стати справжньою зброєю масового ураження при комунікації.

Тому завжди перевіряйте, щоб скорочені версії назв були зручні в щоденному спілкуванні.

Використовуйте довгі або дивні назви для внутрішніх об'єктів

Під словом «внутрішній» я маю на увазі щось, невидимий для кінцевого користувача.

По-перше, завжди переконуйтеся в тому, що внутрішні об'єкти не забирають хороші назви у зовнішніх (видимих) об'єктів. Це дуже важливо: залишайте хороші імена для тих речей, з якими ваші користувачі стикаються найчастіше.

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

Приклад з MVC додатків — UsersController. В даному випадку назва складається з двох частин: Users — вказівка на реальний видимий об'єкт, яким оперує клас, і загальний для всіх контролерів суфікс Controller. І це правильний підхід: усі контролери MVC додатки мають загальну поведінку і код. До того ж це внутрішні об'єкти, які не важливі для кінцевого користувача. Їх назви повинні вказувати на видимі об'єкти, пов'язані з ними.

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

Висновки

Можна виділити три типи назв по функції:

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

І ось кілька принципів іменування:

Використовуйте імена, вже дані користувачами вашого додатка або співтовариства/індустрії в цілому.
Намагайтеся дотримуватися унікальність назв для незв'язаних об'єктів.
Пов'язуйте об'єкти, додаючи однакові слова до назв, тільки якщо вони дійсно пов'язані за змістом.
Уникайте збігу назв у разі їх скорочення.
Давайте більш довгі назви для більш складних об'єктів.
Давайте більш короткі назви об'єктів, які використовуються часто.

Опубліковано: 17/11/17 @ 11:27
Розділ Різне

SEO Блог