Англійська для розробників Elm

Суворі архітектура Elm і відома дружня компілятор виробляють відмінний словник — «Архітектура Elm», «повідомлення», «без винятків під час виконання» — що варто використовувати точно, оскільки розробники Elm розглядають їх як конкретні гарантії, а не маркетингові фрази. Цей підручник містить інформацію про англійську мову, яку використовують під час обговорення коду Elm з командою.

Ключовий словник

** Архітектура Elm (TEA) ** — шаблон Model, Update, View, за яким слідує кожна програма Elm: стан знаходиться у одній моделі, зміни переносяться за допомогою Update, а перегляд відтворюється лише з моделі. “Цей компонент виходить за межі архітектури Elm, щоб змінити значення безпосередньо — все має проходити через Msg і функцію Update замість цього.”

** Повідомлення (Msg) ** — значення, що описує щось, що сталося (натискання кнопки, відповідь сервера), єдиний спосіб, яким зміни стану запускаються в Elm; немає прямої мутації.

• “Замість оновлення моделі в рядку функції перегляду — на що Elm навіть не дозволяє — надсилайте повідомлення і обробляйте зміну стану у вікні оновлення.” *

** Без винятків під час виконання ** — Компілятор Elm гарантує, що компіляційна програма не може завершитися аварійно з нульовою посиланням, невизначеною функцією або невідповідністю типу під час виконання. “Ми не потребуємо захисних перевірок нульових значень, розкиданих по цьому вигляду — компілятор Elm вже гарантує, що це значення не може бути відсутнім, інакше він не був би скомпільований.”

** Decoder ** — значення, яке описує, як розпізнавати і перевіряти нетипізований JSON у певне типізоване значення Elm, явно обробляючи межу між нетипізованими зовнішніми даними і системою типів Elm. “Ця відповідь API не гарантує, що вона відповідає нашій припущенні форми — напишіть правильний декодер з резервним обробником замість припущення, що поле завжди буде присутнім.”

** Команда (Cmd) ** — значення, що описує побічну дію (запит HTTP, що генерує випадкове число), яку виконує час виконання Elm і повідомляє як повідомлення, зберігаючи чистим сам процес оновлення. “Не намагатися викликати HTTP безпосередньо з Update — повертати Cmd, що описує запит, і дати програмі виконання повідомити про результат як про власне повідомлення Msg.”

**Subscription (Sub) ** — оголошення зовнішніх подій (повідомлень WebSocket, таймерів), про які програма Elm бажає бути сповіщеною, які буде надіслано у вигляді повідомлень, так само як і взаємодії користувача.

• “Додати це як підписку, а не запитувати вручну — програма виконання буде доставляти кожне повідомлення WebSocket як Msg саме тоді, коли воно буде отримано.” *

Звичайні фрази

• Чи змінюється цей стан через правильну Msg і Update, чи щось обходить архітектуру?»
• Чи може цей декодер обробляти випадки, коли поле відсутнє або має несподівану форму?
• Чи є це побічним ефектом Cmd, так що Update сам залишається чистим?»
• Чи буде підписка тут чистішою, ніж вручну голосування за цю подію?»
• «Чи компілятор насправді гарантує, що це значення не може бути відсутнім, або ми припускаємо, що це засновано на документації API?»

Приклади висловлювань

Перегляд запиту на звантаження: “Цей декодер припускає, що поле email завжди присутнє, але документація API позначає його як необов’язкове — використовуйте Json.Decode.maybe замість того, щоб не вдалося провести декодування на одному відсутньому полі.”

Пояснення рішення про проектування:

• “Ми створили багатокрокову форму як один тип повідомлення з явними варіантами на крок, отже, оновлення залишається одним вичерпним збігом шаблонів замість розкиданих булевих прапорців.” *

Опис події: “Неочікуваний порожній екран, що слідував за декодером, який беззвучно зазнав невдачі на неочікуваній формі API — оскільки Elm не має винятків під час виконання, вся сторінка просто показувала початкову модель замість аварії.”

Професійні поради

• Скажіть “no runtime exceptions” точно, коли пояснюєте, чому Elm пропускає певні захисні перевірки — це гарантія компілятора, а не припущення, і варто зазначити як таке.
• Назва **« Архітектура Elm » ** явно, коли зміна, здається, обходить очікуваний потік даних — це сигналізує точно, яка конвенція порушується.
• Використовуйте “decoder” замість “parser” при обговоренні меж JSON — це точний термін Elm і відрізняє його від загального аналізу рядків.
• Розрізняйте ** Cmd ** від ** Sub ** — один з них є одноразовим запитом на побічний ефект, а інший — постійною підпискою на зовнішні події; об’ єднання цих двох запитів призведе до плутанини у дизайні.

Практичні вправи

1. Поясніть у двох реченнях, чому Elm не має винятків під час виконання, якщо програма успішно скомпільована.
2. Написати коментар перегляду коду у одному реченні, у якому буде позначено декодер, який завжди приймає поле як присутнє.
3. Опишете вашими словами відмінність між командою Cmd і командою Sub.

На практиці: покращення комунікації з нерідними мовцями

Для багатьох розробників Elm - особливо тих, хто переходить з інших мов або тих, хто не є рідними носієм англійської мови - головним завданням є не тільки розуміння * синтаксису * самого Elm, але і навігація нюансами професійного спілкування. Елегантність дизайну Елм може бути підірвана незграбною фразою, надмірно технічним жаргоном або просто неможливістю чітко сформулювати наміри. Це особливо вірно при обговоренні таких концепцій, як The Elm Architecture (TEA), передавання повідомлень і суворих гарантій компілятора - області, схильні до нерозуміння, якщо не підходити з точністю.

Поширений сценарій виникає під час перегляду коду. Припустимо, що рецензент помічає функцію, яка надмірно покладається на update, а не використовує дії для запуску оновлень. Простий, прямий коментар на кшталт «Це оновлення занадто вкладене; розгляньте рефакторинг, щоб використовувати дію» можна розглядати як критику без контексту. Замість цього, більш корисною формулюванням було б: «Я помітив, що це використовує декілька викликів update. Чи можемо ми спростити це, запропонувавши певну дію, яка викликає зміну стану? Це покращить читабельність і спростить обґрунтування потоку оновлень. » Зауважте, що мова йде про те, * чому* пропонується ця зміна — покращення читабельності, сприяння яснішому обґрунтуванню — а не просто про висловлення думки. Аналогічно, в обговореннях Slack, уникаючи надто технічних термінів, таких як «незмінність», коли обговорюється виправлення помилок, пов’язаних зі змінами структури даних, може поліпшити розуміння для тих, хто менш глибоко знайомий з основними принципами Elm. Фрази на кшталт «Ця зміна запобігає випадковій мутації стану» є набагато доступнішими, ніж «Незмінна природа цього запису забезпечує…»

Крім того, важливе значення має створення ефективних описів PR. Хороший опис повинен чітко пояснити * що * було змінено і, що важливо, * чому *. Не просто перелічуйте рядки коду, які було додано або вилучено; описуйте проблему, яку ви вирішуєте, і яким чином ваше рішення вирішує цю проблему. Наприклад: «Відомо, що користувачі не завжди розуміють, що робити з цими файлами. Введено новий PreferencesAction для обробки оновлень параметрів і забезпечення їх серіалізації зі станом програми.» Цей рівень деталізації зменшує неоднозначність і дозволяє переглядачам швидко зрозуміти мету зміни, навіть якщо вони не дуже добре знайомі з певною частиною коду.

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

elm reactor --inspect