アナライザーのコメントを書く

このドキュメントでは、アナライザーが生成するコメントの書き方に関する情報とガイドラインを紹介します。

内容

アナライザーのコメントの内容は、exercism/website-copyリポジトリにMarkdownドキュメントとして保存されています。 各コメントには、<track-slug>.<exercise-slug>.<comment-slug>という形式のポインター文字列が含まれており、これがwebsite-copyリポジトリ内の特定のMarkdownドキュメントを指します。

たとえば、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のメンタリング全般に共通する助言として、解答は与えないようにしましょう。 人は自分で答えを発見したときに、学びが定着します。それはこの上なく爽快な体験であり、その感情の高ぶりが記憶に残るものにします。 ただし、その発見がドーパミン的な快感を引き起こさない場合は、答えがどんな形かを示すことは十分に理にかなっています。 たとえば、承認された解答に小さな改善を提示するのは、否認されつつある解答に学習ポイントを伝えるよりもはるかに面白みに欠けます。そのような場合は、リンクよりも実例を示すのがふさわしいでしょう。
• コメントは重要度順に並べましょう。最初のコメントが最も重要で、最後のコメントが最も重要度が低くなるようにします。
• コメントの数は扱いやすい範囲に抑えましょう。 1回の繰り返しにつき1〜3件を目安にしましょう。
• 1回の分析で同じコメントを2回追加しないでください。 同じコメントに異なるパラメーターを付け加えたものは、重複とはみなし_ません_。
• フォーマットについてのみコメントすることも検討しましょう。ただし、フォーマットやリントがその言語にとって不可欠な場合に限ります。 可能であれば、学習者を自動フォーマットのツールへ導き、公式のスタイルガイドがあればリンクを貼りましょう。

最初のいくつかの演習

トラックの最初のいくつかの演習では、次の点が_とくに_重要です。

• 比較的短く保ちましょう。文章の壁を作ったり、アドバイスで相手を圧倒したりしないようにします。最初の演習で良い体験ができれば、相手はまた戻ってきてくれます。そうすれば、気づいたすべての点についてフィードバックする機会が何度も訪れます。
• 概念を過剰に説明しないようにしましょう：コンパイラーなどの背後にある仕組みを深く掘り下げる必要はありません。ここで大切なのは、これが言語トラックの最初のほうの演習のひとつだという点です。この段階では、フィードバックは短く、より指示的なほうが役立ちます。
• チュートリアルのように、その概念のやり方を具体的に示すリンクを挙げましょう。つまり、なぜそうするのかを論じるのではなく、どうやるのかを示すものです。言語の公式ドキュメントでは足りないこともあります。公式ドキュメントはコードのリファレンスであることが多く、使い方や仕組みを示してくれないからです。ただし、リンクを挙げるのはより深く掘り下げたい場合だけにしましょう。相手はリンクをたどらなくても、回答そのものから意図を理解できるべきです。

例

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

コメントはアナライザーと同じリポジトリにないため、各アナライザーには、そのアナライザーで使われるコメント（出力になりうるもの）が、exercism/website-copyリポジトリのmainブランチ上のコメントであるかどうかを確認するCIを用意すべきです。

執筆時点では、このCIを一般化する取り組みがあるかどうか、その状況をこのissueで追跡しています。