분석기 코멘트 작성

이 문서는 분석기가 생성하는 코멘트를 어떻게 작성해야 하는지에 대한 정보와 지침을 제공해요.

내용

분석기 코멘트의 내용은 exercism/website-copy 저장소에 마크다운 문서로 저장돼요. 코멘트에는 <track-slug>.<exercise-slug>.<comment-slug> 형식의 포인터 문자열이 있고, 이 문자열은 website-copy 저장소의 특정 마크다운 문서를 가리켜요.

예를 들어 ruby.two-fer.string-interpolation은 https://github.com/exercism/website-copy/blob/main/analyzer-comments/ruby/two-fer/string_interpolation.md를 가리켜요.

Note

코멘트가 언어에만 해당하고 연습 문제에는 해당하지 않는다면, <exercise-slug>를 general로 바꿔요. 예: ruby.general.string-explicit_return

문구

  • 불필요하게 장황한 코멘트는 피해요. 간결하게 써요.
  • 중립적으로 관찰한 내용만 담고, 감정이 실린 표현이나 지나친 일반화는 피해요.
  • 권고 사항을 분명하게 밝혀요.
  • 가능하면 권고를 먼저 쓰고, 설명을 뒤에 붙여요.
  • 봇은 사람이 아니므로 "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에서 한 학습자가 내장된 오류 대신 직접 정의한 error를 만들었어요:

<!-- 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를 일반화한 것이 있는지에 대한 현황은 이 이슈에서 추적하고 있어요.