Написання коментарів аналізатора

Цей документ містить інформацію та настанови про те, як писати коментарі, які створює аналізатор.

Зміст

Тексти коментарів аналізатора зберігаються як документи Markdown у репозиторії exercism/website-copy. Коментарі містять вказівник у вигляді рядка тексту (англ. string) у форматі <track-slug>.<exercise-slug>.<comment-slug>, який посилається на конкретний документ Markdown у репозиторії website-copy.

Наприклад, ruby.two-fer.string-interpolation вказує на https://github.com/exercism/website-copy/blob/main/analyzer-comments/ruby/two-fer/string_interpolation.md.

Формулювання

• Уникаймо зайвої багатослівності в коментарях. Пишімо стисло.
• Описуймо нейтрально, уникаймо емоційних та узагальнювальних тверджень.
• Формулюймо рекомендацію чітко.
• Коли це можливо, спершу ставмо рекомендацію, а вже потім пояснення.
• Уникаймо «me», «I», «we» тощо, бо бот не є людиною.
• Уникаймо «you» та «your code», бо це часом звучить як осуд людини, а не коду.
• Уникаймо слів як-от «just», «simply», «obviously», які можуть звучати поблажливо: якщо коментар потрібен, то це очевидно не було очевидним.
• Не робімо припущень про те, що люди знають, а чого ні. Єдиний виняток - знання з уже виконаних основних вправ. Уникаймо зворотів «as you know», «as you remember», «as you learned», «now that we all understand x», бо навіть якщо щось було сказано, людина не обовʼязково це зрозуміла.

Настанови

• Прагнімо вільного володіння, а не вправності: мета мовного треку на Exercism - дати людям спосіб досягти високого рівня вільного володіння за низького рівня вправності. Ми прагнемо вільного володіння синтаксисом, ідіомами та стандартною бібліотекою мови.
• Радьмо ідіоматичний код, коли це можливо, де ідіоматичний код - це код, який написали б майже всі розробники (не аматори), які пишуть код цією мовою. Якщо ми пропонуємо щось неідіоматичне, скажімо про це і пояснімо, чому пропозиція все одно може бути корисною.
• Називаймо різницю між тим, що робить людина, і тим, що є «ідіоматичним» у мові.
• Уживаймо правильні терміни й номенклатуру, щоб люди могли впізнати ці поняття в інших місцях і самостійно їх дослідити.
• Не даваймо рішення як загальну пораду для всього наставництва на Exercism. Знання тримаються, коли люди самі доходять відповіді. Це неймовірно піднесний досвід, а емоційний поштовх робить його незабутнім. Однак, якщо відкриття не викликає викиду дофаміну, цілком логічно показати, як воно має вигляд. Наприклад, невелике покращення до схваленого рішення буде значно менш захопливим, ніж навчальний момент для рішення, яке ми не схвалюємо, і тому тут доречніше дати приклад, а не посилання.
• Упорядковуймо коментарі за важливістю: перший коментар - найважливіший, а останній - найменш важливий.
• Тримаймо кількість коментарів під контролем. Прагнімо, щоб на ітерацію припадало від одного до трьох коментарів.
• Не додаваймо той самий коментар двічі в одному аналізі. Той самий коментар з іншими параметрами не вважається дублікатом.
• Розгляньмо можливість коментувати лише форматування, якщо форматування чи лінтування є невіддільною частиною мови. Коли можливо, скеровуймо студентів до інструментів автоматичного форматування та/або додаваймо посилання на офіційний посібник зі стилю.

Перші кілька вправ

Для перших кількох вправ треку особливо важливо таке:

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

Приклади

У JavaScript студент написав константу верхнього рівня за допомогою let.

<!-- not following these guidelines -->

As you know, everyone uses const, you shouldn't use let or var.

Цей коментар не дотримується цих настанов із таких причин:

• Дія йде після «пояснення».
• «As you know»: ми не знаємо, чи студент справді це знає.
• «you shouldn't»: «you» тут не потрібне, щоб зробити це твердження.
• «everyone uses const»: це неправда і може змусити студента відчути, ніби він зробив щось жахливо неправильно.
• Бракує власне пояснення, чому дано цю пораду.

<!-- better -->

Prefer `const` and `let` over `var`. The `const` declaration stops a variable
from being accidentally reassigned, which provides safety, and reduces
cognitive load for someone reading the code. [This article](https://medium.com/javascript-scene/javascript-es6-var-let-or-const-ba58b8dcde75)
explains the difference between the three.

У Go студент створив власну помилку замість вбудованих:

<!-- not following these guidelines -->

I see you are creating a custom `error`. This is perfectly fine! If you did not
know about `errors.New` and `fmt.Errorf` have a look at them as they are much
simpler ways to create an error. Custom errors are helpful if you want to check
if an error is of a certain type later.

Цей коментар не дотримується цих настанов із таких причин:

• «I see»: аналізатор не є людиною, тож уникаймо «I».
• «This is perfectly fine!»: очевидно, це не так, інакше запевнення було б не потрібне. Це, ймовірно, можна взагалі прибрати; якщо ми хочемо дати загальну пораду про щось наявне, можна сказати саме так: «An alternative, equally valid way of doing x is y.»
• «If you did not know about»: прибираймо цю надто багатослівну групу слів.

<!-- better -->

A custom `error` is typically used to provide custom behavior, or to distinguish
on type later. For simpler cases, it's more common to rely on `errors.New` or
`fmt.Errorf`. This [in-depth article](https://golangbot.com/custom-errors/) about
custom errors might be interesting.

CI

Оскільки коментарі не лежать у тому самому репозиторії, що й аналізатор, кожен аналізатор повинен мати CI, який перевіряє, чи коментарі, використані в цьому конкретному аналізаторі (ті, що можуть стати вихідними даними), є коментарями на гілці main у репозиторії exercism/website-copy.

На момент написання це issue відстежує стан будь-якого узагальнення цього CI, якщо воно є.