Змістовні стислі способи іменування вказівок

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

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

Наприклад, це може бути частиною рекомендацій, які я дотримуюся:

• Використовуйте Додати, коли наявний елемент буде додано до цілі, Використовуйте Створити, коли новий елемент створюється та додається до цілі.
• Використовуйте Видалити, коли існуючий елемент буде видалено з цілі, Використовуйте видалити, коли елемент буде видалено назавжди.
• З'єднайте методи AddXXX із методами RemoveXXX та Pair CreateXXX із методами DeleteXXX, але не змішуйте їх.

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

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

Іменування. Одна з найскладніших речей щодо розробки програмного забезпечення :)

Коли я щось називаю, ось мій набір пріоритетів:

• Дотримуйтесь ідіоми моєї мови. Рубі подобається підкреслення. Javascript любить верблюжий чохол. Якою б мовою ви не користувалися, це дотримання конвенції.
• Виявляє наміри API. Це не "send_http_data", це "post_twitter_status"
• Уникайте деталей щодо впровадження. Скажіть, префіксація змінної типом.
• Не використовує більше символів, ніж потрібно, не порушуючи попередні вказівки.

Очевидно, що це досить спрощений підхід. Названня є нюансом.

Для подальших досліджень я рекомендую прочитати «Art of Readable Code» , оскільки він пропонує чудові, стислі поради щодо назви методів. Для ще більшого дослідження я не можу більше рекомендувати чистий код Боба Мартіна

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

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

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

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

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

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

Код повинен бути самодокументуванням, тобто ваше називання повинно дати зрозуміти, що щось робить. Якщо вам потрібно пояснити, що робить рядок коду в коментарі, а перейменування речей недостатньо покращить його, слід серйозно розглянути можливість рефакторингу цієї лінії в новий метод із відповідним описовим іменем, щоб читати оригінальний метод, новий виклик методу описує те, що відбувається. Не бійтеся мати довгі імена; звичайно, ви не повинні писати романи в назви класів / методів / змінних, але я вважаю за краще, щоб ім’я було занадто довгим і описовим, ніж занадто коротким, і мені потрібно з'ясувати, що це робить, заглядаючи під капот. За винятком явних винятків, таких як координати x / y та часто використовувані абревіатури, уникайте одноіменних імен та скорочень. Викликати щось "bkBtn" замість "backButton"

Наскільки дозволяє ваша мова, зробіть свій код прочитаним як англійське речення. Об’єкти використовують іменники, методи використовують дієслова. Булеві методи, як правило, починаються з "є", але існує багато інших варіантів, які передають значення ще краще, залежно від випадку використання, наприклад "може", "повинен" або "робить". Звичайно, не всі мови можуть бути настільки ж хорошими, як Smalltalk, але деякі символи, як правило, розуміються як частини речення. Дві конвенції Smalltalk, які я особисто якнайбільше використовую в інших мовах, - це префіксація назви параметрів циклу "кожний", а також параметри методу префіксації статтею "a" (або "an", або "some" для колекцій) . Це не може бути звичайним стандартом на Java, і кожен бажає ігнорувати цей біт, але я вважаю, що це значно підвищує читабельність коду. Наприклад (на прикладі Java):

public boolean shouldConsiderAbbreviating(List<String> someNames) {
  for (String eachName : someNames) {
    if (isTooLong(eachName)) {
      return true;
    }
  }
  return false;
}

Це має бути зрозумілим людям, які лише трохи знають Java як щось подібне:

Щоб визначити, чи слід розглядати скорочення списку деяких імен (які є рядками), перебирайте деякі імена та для кожного імені визначайте, чи занадто він довгий; якщо так, поверніть true; якщо жодна не надто довга, поверніться false.

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

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

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

Взагалі, розгляньте речі, подібні object.method(parameters)до такої схеми subject.verb(complements).

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

Щодо іменників, класи повинні бути названі для того, що вони are(в терміні поняття), а об'єкти для чого вони are for.

Що сказати, між list.add(component)і component.add_to(list)віддайте перевагу першому. Взагалі дієслова «активні перехідні» краще відображають дії щодо їх пасивних чи рефлексивних аналогів. Якщо тільки дизайн не обмежує вас.

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

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

public User Find(int userId);

простіше зрозуміти, ніж:

public Person Find(int personId);

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

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

Деякі платформи віддають перевагу коротким іменам (наприклад, в Win32 C API _tcsstr- це функція пошуку рядка в рядку - чи не очевидно це?), Інші йдуть на читабельність на користь стислості (в рамках какао Apple для Objective-C , називається метод заміни підрядка в рядку іншим рядком і повернення результату у вигляді копії stringByReplacingOccurrencesOfString: withString:). Я вважаю, що останнє набагато простіше зрозуміти, і лише помірно важче писати (особливо із заповненням коду).

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

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

2. Вивчіть загальноприйняті конвенції та стилі імен. Вашим керівним принципом має бути чіткість. Стилі відрізняються мовою програмування.

3. З іменуванням нічого не можна зробити, що полегшить розуміння зв’язків між різними об'єктами у вашому коді. Для цього вам все ще потрібні добре написані коментарі та документація.

1. Використовуйте префікс. Якщо купа методів використовується для того, щоб зробити щось подібне, або їх можна якимось чином згрупувати, поставте загальний префікс перед їхніми іменами, щоб показати, що цих методів має спільне.
2. Не використовуйте незрозумілу абревіатуру, якщо ви хочете, щоб інші миттєво розуміли імена (важливо в іменуванні API)