Англійська для написання кодів виходу і повідомлень про помилки CLI

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

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

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

** Повідомлення про помилку, яке можна виконати ** — повідомлення про помилку, яке повідомляє користувачеві не лише про те, що сталося не так, але і про те, що робити з цією помилкою.

• “Замість « некоректний вхід », версія, що може виконувати дії, повідомляє « некоректний вхід: очікувалося число для параметра — timeout, отримано ” abc\ "". Спробуйте —timeout 30.’” *

** Рядок використання ** — коротке резюме, яке буде показано, якщо CLI буде викликано неправильно, з показом очікуваного синтаксису. “Якщо відсутні необхідні аргументи, ми виводимо рядок використання: ‘Використання: mytool deploy —env <staging|production> [—dry-run]’.”

** Прапорець Verbose / debug ** — прапорець, який уможливлює додаткове діагностичне виведення, на яке посилаються у повідомленнях про помилки, щоб повідомити користувачам, як отримати більше відомостей. “Повідомлення про помилку закінчується словами «Запустити з — verbose для повного стека», щоб користувачі знали, як отримати більше інформації без типового списання даних.”

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

• “Це була мовчазна помилка — скрипт завершився з 0, навіть якщо вивантаження зазнало невдачі, оскільки ми не перевіряли стан відповіді. Тепер це виправлено, і він виходить 1 з ясним повідомленням.”*

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

• « Помилка: [особлива проблема]. [Особливе запропоноване виправлення]. »
• «Очевидним є [X], а очевидним є [Y]»
• «Запустити з —verbose для більшої деталізації»
• «Коди виходу [N]: [категорія невдачі]»
• «Див. [команда] —help для використання.»

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

Запис помилки, що може бути виправлена, замість нечіткої помилки:

• « Помилка: не вдалося з’ єднатися з базою даних на localhost: 5432 (з’ єднання відмовлено). Чи запущена база даних? Спробуйте «docker compose up db» або перевірте DATABASE_URL у вашому файлі.env.”*

Документування кодів виходу у README або виводі довідки:

• “Коди завершення: 0 = успіх, 1 = загальна помилка, 2 = невірні аргументи, 3 = файл налаштувань не знайдено, 4 = помилка мережі. Скрипти, що викликають цей інструмент, можуть розгалужуватися на цих кодах, щоб обробляти помилки по-різному.”*

Написання рядка використання, який залишається коротким, але повним: “Використання: backup-cli restore —snapshot [—target ] [—dry-run] Запустіть ‘backup-cli restore —help’, щоб отримати повний список параметрів.”

Виправлення мовного збою і пояснення зміни у журналі змін:

• “Відомо, що команда sync раніше завершувала роботу з кодом 0, навіть якщо вивантаження окремих файлів зазнавали невдачі у фоновому режимі. Тепер він чекає, поки всі завантаження завершаться, явно повідомляє про помилки і виходить з кодом 1, якщо який-небудь файл не вдалося синхронізувати.”*

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

• Структурувати повідомлення про помилку як проблема + конкретне виправлення, а не просто проблема — “очікувалося число, отримано «abc». Спробуйте — timeout 30” значно корисніше, ніж « некоректний вхід. »
• Задокументуйте вашу ** схему кодів виходу ** у доступному місці (README, --help, сторінка довідника) — скрипти і конвеєри CI залежать від того, чи стабільні і задокументовані коди виходу, а не від того, чи можна їх вгадати.
• Ніколи не дозволяти програмі успішно завершити роботу після часткової невдачі — якщо щось пішло не так, код завершення і повідомлення повинні вказати на це, навіть якщо загальна операція « переважно » була успішною.
• Зберігати ** перший рядок помилки ** коротким (це те, що з’ являється у буфері прокрутки або підсумку журналу CI), і розміщувати розширені подробиці за прапорцем --verbose, замість типового списання всіх даних.
• Використовуйте послідовні формулювання у всіх повідомленнях про помилки вашого інструменту — якщо ви використовуєте « Очікувалося X, отримано Y » у одному місці, використовуйте ту ж саму структуру усюди, щоб користувачі могли швидко навчитися аналізувати ваші помилки.

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

1. Переписати нечітке повідомлення про помилку (« некоректні налаштування ») у повідомлення, яке можна виконати, з конкретним запропонованим виправленням.
2. Написати коротку таблицю кодів виходу для гіпотетичного інструменту CLI з чотирма категоріями помилок.
3. Написати запис журналу змін, який описує виправлення вади, що призвела до вимушеної відмови.

Мова мови: мова для немовлят

Написання чітких кодів виходу і повідомлень про помилки CLI є основою хорошого технічного спілкування. Це не просто про те, що * що * пішло не так; це про керування користувачем до рішення. Однак, для розробників, чия перша мова не є англійською, навігація нюансами професійного фразування може бути особливо складною. Часто буквальні переклади або надмірно формальна мова можуть призвести до повідомлень, які технічно точні, але практично не корисні - заплутані і розчаровані для будь-кого, хто намагається швидко вирішити проблему. Розглянемо, як це застосовується, наприклад, при отриманні коментаря перегляду коду. Уявіть, що ви надіслали PR, у якому міститься новий скрипт, призначений для автоматизації резервування баз даних. Під час перегляду ваш старший інженер залишає коментар: « Код виходу 13 вказує на помилку відмови у дозволі. Це потребує більшого контексту – * чому * користувач не має доступу. » Прямий переклад « дозволу відмовлено » може бути цілком зрозумілим, але додаткове наголошення на « чому » і інструкція надати * більше контексту * є ключовими для когось, хто вивчає англійську в професійному середовищі. Це розуміння очікувань, що вам потрібно пояснити кореневу причину, а не просто повідомити про симптом.

Інший поширений сценарій виникає під час розмов Slack при усуненні проблем з інструментами CLI. Припустимо, що молодший розробник надсилає повідомлення: « Команда зазнала невдачі з кодом 255. » Корисною відповіддю, призначеною для когось, хто ще тільки починає розвивати свої знання англійської мови, може бути: « Гаразд, це загальний код помилки. Чи можете ви, будь ласка, вказати, що це за команда і що вона намагалася зробити? Знаючи точну команду, ми можемо швидше діагностувати проблему. » Використання таких фраз, як « конкретно » і « допомагає нам діагностувати », надає більш чітке керівництво, ніж просто вказування самого коду помилки. Аналогічно, під час створення описів PR для нових інструментів CLI або скриптів, уникайте надто технічного жаргону, якщо це не абсолютно необхідно. Замість цього, зосередьтеся на ясних, реальних інструкціях, написаних простою англійською. Наприклад, замість « Використовувати grep -i для фільтрування результатів », розгляньте: « Використовувати цю команду для пошуку всіх рядків, що містять вказане ключове слово, ігноруючи регістр. »

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

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