Англійською мовою: Vale Prose Linting

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

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

Стиль — названа збірка правил (наприклад, Google, Microsoft або нетиповий стиль), які Vale застосовує до документа, аналогічно до набору правил linter або попереднього налаштування конфігурації. “Ми розширюємо стиль Microsoft з декількома нетиповими правилами, а не пишемо стиль з нуля — більшість їх базових рекомендацій вже відповідає тому, що ми хочемо.”

** Правило ** — одинична перевірка у стилі, визначеному у файлі YAML, яка позначає певний шаблон (пасивне голосування, заборонений термін, непослідовне використання регістру) у прозі.

• “Це правило походить від правила « FirstPerson » — ми навмисно дозволяємо вправи від першої особи, отже, нам слід розширити обсяг цього правила, щоб виключити каталог вправ.” *

** Рівень серйозності ** — класифікація ( suggestion, warning, error ), яка призначена для порушення правил, визначає, чи це порушення просто з’ являється на виході або ж воно дійсно не вдалося CI. “Зменшити ступінь тяжкості цього правила до попередження замість помилки — це корисне повідомлення, але воно не повинно само по собі блокувати об’ єднання.”

** Vocab (список слів) ** — специфічний для проекту список прийнятих і відхилених термінів (наприклад, схвалених назв продуктів або заборонених жаргонів), з якими Vale перевіряє прозу, відрізняється від загальної перевірки правопису. “Додати « Turbopack » до списку прийнятих словників — це справжня назва продукту, а не друкована помилка, і її продовжують фіксувати.”

** Область ( .vale.ini BasedOnStyles) ** — налаштування, які відповідають певним шаблонам файлів або каталогів, до яких застосовуються стилі і правила, що дозволяє різним розділам документа слідувати різним правилам. “Сторінки з посиланнями на API мають більш строгий стиль, ніж блог — це навмисне, оскільки посилання на документацію потребують більш жорсткої послідовності, ніж оповіді про публікації.”

** Alert ** — окремий повідомлений екземпляр правила, який було викликано у певному рядку і стовпчику, фактичний об’ єкт виводу, який бачить і адресує програміст, подібно до окремого рядка з прапорцем у програмі linter.

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

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

• «Чи це позначене правилом, яке ми насправді хочемо впровадити, або ми повинні виключити його для цього типу файлів?»
• Яка тяжкість цього правила — чи це насправді блокує CI, чи це просто пропозиція?»
• Чи є цей термін у прийнятому списку слів, чи це справді типографська помилка?
• Чи правильно цей стиль, чи він застосовується до файлів, яких він не повинен торкатися?»
• «Скільки попереджень є реальні проблеми проти хибних позитивних з цього правила?»

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

Пояснення зміни налаштувань Vale у PR:

• “Я розширив сферу дії більш суворих правил термінології лише на теку посилання docs — застосування їх до блогових статей давало занадто багато хибних позитивних результатів у випадках навмисного неформального написання.” *

Звітування про хибно позитивний результат: “Правило пасивного голосу позначає коментар коду всередині огороженого блоку як прозу — ми повинні або виключити блоки коду з цього правила, або знизити його тяжкість, щоб воно не провалилося CI.”

Обговорення рішення щодо стилю з технічним автором:

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

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

• Посилання на ** конкретну назву правила ** при обговоренні попередження Vale — « linter скаржиться » так само не допоможе для прози, як і для коду linter без ідентифікатора правила.
• Встановіть ** рівень суворості ** навмисно і поясніть причину у налаштуваннях — правило, встановлене на error без обговорення, має тенденцію до тихого вимикання з розчарування, а не до виправлення.
• Активно підтримувати ** список слів **, оскільки назви продуктів і інструментів змінюються — застарілий список слів створює шум, який підриває довіру до інших, справді корисних попереджень linter.
• Використовуйте точність ** scope **, коли пропонуєте нове правило — застосування стилю до всього проекту, а не до певного типу документа, для якого він призначено, є поширеним джерелом перевизначення.

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

1. Поясніть у одному реченні різницю між стилем і правилом у Vale.
2. Написати опис PR, який визначає обсяг дії правила на певний каталог.
3. Опишете вашими словами, для чого використовується список слів.

Розширення вашого арсеналу: ефективно спілкуватися з Vale

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

Розглянемо такий сценарій: Ви отримали коментар щодо запиту на звантаження, у якому описано порушення стилю. У коментарі не просто написано « Виправити цей відступ ». Замість цього у ньому написано: « У цьому розділі можна було б використовувати більш послідовні інтервали навколо операторів, щоб полегшити читання для супроводжуючих. Розгляньте можливість вирівнювання з встановленим нами стилем команди — ми, як правило, віддаємо перевагу 4 проміжкам. ” Це відразу додає контекст і виправдання. Мова підкреслює потенційний * вплив * - поліпшення читабельності - а не просто заяву про правило. Він також вводить концепцію «командного встановленого стилю керівництва», що має вирішальне значення для розуміння того, де Vale вписується в більший робочий процес розробки. Аналогічно, в розмовах Slack, де обговорюється вихідний код Vale, ви можете почути, як хтось каже: «Я бачу багато цих «незначних» порушень - можливо, нам слід приоритизувати їх як частину наших майбутніх зусиль з рефакторингу?» Це демонструє здатність класифікувати проблеми за тяжкістю і пов’язувати їх зі стратегічними пріоритетами. Зрозуміти нюанси фраз, таких як «незначний», «головний» або «рекомендований» є ключовим, оскільки ці терміни мають значну вагу в дискусіях про пріоритетність і розподіл ресурсів.

Інша поширена ситуація включає написання опису PR * перед * надсиланням його. Замість того, щоб просто сказати, «Vale linting passed», ви можете написати: «Ця публікація включає оновлену документацію, щоб дотримуватися правил стилю Vale, особливо звертаючись до відступів і інтервалів, які виникли під час процесу перегляду. Зміни були внесені для покращення ясності коду і підтримки відповідно до стандартів команди. ” Цей активний підхід демонструє прихильність до якості і показує, що ви розглянули зворотній зв’ язок, наданий лінтером. Це робить роботу не просто виправленням помилок, а активним внеском у кращу базу коду.

Нарешті, пам’ятайте, що вивід Vale надає дані - інформацію про те, що * що * не так. Вам нужно перевести эти данные в практические идеи. Не просто скажіть « Vale позначила це ». Поясніть * чому * це було позначено і які потенційні наслідки може мати ігнорування цього повідомлення.

vale --config-file=my_vale_config.yaml .

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