Exercism 스타일 가이드

이 문서는 연습 문제에서 사용하는 언어와 표현에 대한 스타일 가이드 역할을 해요.

적용

이 규칙은 모든 연습 문제에서 따라야 해요. 기존 설명과 테스트 케이스는 "대체" 테스트 케이스 없이도 이 규칙에 맞게 수정할 수 있어요.

연습 문제 내에서의 일관성

여러 가지 표기가 모두 맞는 용어가 있어요(예: "lower case"와 "lowercase"). 이 문서에서 일관된 표기를 정하지 않은 경우에는, 연습 문제 안에서 일관되게 사용해야 해요.

예외

메인테이너들 사이에 이것이 합리적이라는 일반적인 합의가 있다면, 연습 문제는 이 규칙에서 벗어날 수 있어요. 예를 들어, 서로 다른 단위 사이의 변환을 다루는 연습 문제는 SI 단위를 쓰지 않기로 할 수도 있어요.

언어

모든 콘텐츠는 미국식 영어로 작성해야 해요. 미국식 영어는 영국식 영어와 여러 면에서 달라요. 앞으로 다른 언어로의 번역이 이루어질 수도 있지만, Exercism의 "공식" 언어는 미국식 영어예요.

측정 단위

모든 측정 단위는 SI 단위나 SI 파생 단위여야 해요.

약어, 두문자어, 머리글자어

약어, 두문자어, 머리글자어는 다른 표현보다 이해하기 어려운 경우가 많고, 배우려는 사람을 멀어지게 만들 수 있어요.

많은 약어는 전문 용어예요. 가능하면 다른 표현을 써서 전문 용어를 피해요. 다음 둘 중 하나에 해당할 때만 약어를 써요.

  • 약어가 원래 용어보다 더 잘 알려져 있을 때
  • 약어를 쓰지 않으면 글이 지나치게 길어질 때

약어를 쓸 때는 항상 처음 나올 때 그 용어의 뜻을 설명해요. 여기에는 약어를 원래 형태로 풀어 쓰는 것이 자주 포함되지만, 항상 그런 것은 아니에요. 약어를 풀어 쓰는 것만으로 충분한 경우는 드물어요.

몇 가지 예시 규칙을 볼까요.

  • "IIRC"보다 "if I recall correctly"를 선호해요
  • "AFAIK"보다 "as far as I know"를 선호해요
  • "FIFO"보다 "queue", "FILO"보다 "stack"을 선호해요
  • 인터페이스를 "RESTful"이라고 설명하는 대신, 그 구체적인 속성을 설명해요
  • "CRUD"를 꼭 써야 한다면, Create, Read, Update, Delete를 뜻하며 이것이 표준 데이터베이스의 기본 동작이라는 점을 설명해요

잘 쓴 예시도 있어요.

  • "HyperText Markup Language (HTML) is the language used to describe document structure and content on the web" (풀어 쓰고 설명했어요)
  • "DNA, a set of chemical instructions that influence how our bodies are constructed" (DNA는 풀어 쓰지 않았어요. "deoxyribonucleic acid"가 우리 독자에게 DNA가 무엇인지 설명하는 데 도움이 되기 어렵기 때문이에요)
  • "NASA, the United States' space agency, launched the Mariner 2 space probe in..." (NASA는 풀어 쓰지 않았어요. "National Aerospace and Space Administration"은 원래 이름보다 두문자어로 훨씬 더 잘 알려져 있기 때문이에요)
  • "The Department of Motor Vehicles (DMV) is filled with sloths. That's why everything takes forever at the DMV" (DMV를 처음 쓸 때 정의했어요)

문법

옥스퍼드 쉼표

목록에서는 "옥스퍼드 쉼표"(직렬 쉼표라고도 불러요)를 사용해요. 예를 들어, "I love my parents, Lady Gaga and Humpty Dumpty"라고 쓰는 대신 "I love my parents, Lady Gaga, and Humpty Dumpty"라고 써요. 설명을 담은 이 이미지도 재미있게 볼 수 있어요.

예외

어떤 약어는 충분히 흔하고 유용하며 기술적이지 않다고 판단해서 허용하기로 했어요.

  • e.g. 또는 eg
  • i.e. 또는 ie
  • etc. 또는 etc
  • docs

축약형(예: "won't", "I'm", "that's")은 연습 문제 설명에서는 가급적이면 아예 쓰지 않는 게 좋지만, 사이트의 다른 글(예: 웹사이트 문구, 멘토링)에서는 제한하지 않아요.

많은 미국식 영어 스타일 가이드에서는 "i.e."와 "e.g." 뒤에 쉼표를 붙이라고 해요(예를 들어 이 StackExchange 글을 참고해요). Exercism의 글에서는 이게 허용되지만, 필수는 아니에요.

단어 선택

수학 용어와 전문 용어

수학 용어를 쓰는 곳에서는 그 용어를 설명하거나, 더 적은 배경 지식을 요구하는 표현으로 바꿔야 해요.

예시:

  • "natural numbers" 대신 "positive whole numbers"를 써야 해요.
  • "rational numbers"라는 표현을 쓰고 싶다면, 연습 문제의 도입부에서 설명해야 해요.
  • range라는 단어(문맥에 따라 다른 뜻이 될 수 있어요) 대신 "x < ? < y (greater than x and less than y)"를 써요.
  • "esoteric terms" 대신 "terms not understood by the majority of people"라는 표현을 써요.

코드

모든 코드는 해당 트랙의 스타일 규칙에 따라 일관되게 작성해야 해요. 가능하면 트랙 전체의 규칙은 그 언어에서 선호하는 스타일 규칙과 맞추는 게 좋아요.