[책요약] 읽기 좋은 코드가 좋은 코드다 6장 명확하고 간결한 주석 달기

2020-10-08

6장 명확하고 간결한 주석 달기

주석은 높은 ‘정보 대 공간’ 비율을 갖춰야 한다.

6.1 주석을 간결하게 하라

// int는 CategoryType이다
// 내부 페어의 첫 번째 float는 'score'다.
// 두 번째는 'weight'다.
typedef hash_map<int, pair<float, float>> ScoreMap;
// CategoryType -> (score, weight)
typedef hash_map<int, pair<float, float>> ScoreMap;
  • 한줄이면 충분한 주석이다.

6.2 모호한 대명사는 피하라.

// Insert the data into the cache, but check if it's too big first.
// 데이터를 캐시에 넣어라. 하지만 그것이 너무 큰지 먼저 확인하라.
  • ‘it’은 데이터를 가리킬 수도 있고, 캐시를 가리킬 수도 있다.
  • 혼동의 여지가 조금이라도 있으면 대명사를 원래 명사로 대체
// Insert the data into the cache, but check if the data too big first.
  • ‘it’을 완전히 명확하게 하기 위해 문장을 고칠 수도 있다.
// If the data is small enough, insert it into the chche.
// 데이터가 충분히 작으면, 이를 캐시에 넣어라.

6.3 엉터리 문장을 다듬어라

# 이 URL을 전에 이미 방문했는지에 따라서 다른 우선순위를 부여한다.
# 전에 방문하지 않은 URL에 높은 우선순위를 부여하라.
  • 아래 문장이 더 간단하고, 짧고, 직접적이다.

6.4 함수의 동작을 명확하게 설명하라.

// 이 파일에 담긴 줄 수를 반환한다.
int CountLines(string filename) {
    ...
}
  • 이 주석은 그다지 명확하지 않다.
  • ‘줄’을 정의하는 방법은 여러가지 이기 때문이다.
    • ’‘(빈파일)은 줄수가 0인가 1인가?
    • ‘hello’는 줄 수가 0인가 1인가?
    • ‘hello\n’은 줄수가 1인가 2인가?
    • ‘hello\n world’는 줄 수가 1인가 2인가?
    • ‘hello\n crue\n world\n’은 줄수가 2,3,4 중 어느 것인가?
  • 가장 간단한 구현은 단순히 개행문자(\n)를 세는것이다.
// 파일 안에 새 줄을 나타내는 바이트('\n')가 몇 개 있는지 센다.
int CountLines(string filename) {
    ...
}

6.5 코너케이스를 설명해주는 입/출력 예를 사용하라.

  • 신중하게 선택된 입/출력 예는 천 마디 말보다 위력적이다.
// 입력된 'src'의 'chars'라는 접두사와 접미사를 제거한다.
String Strip(String src, String chars) {
    ...
}
  • 이 주석은 다음과 같은 질문에 답하지 않으므로 명확하지 않다
    • chars가 제거되어야 하는 정확한 부분 문자열을 의미하는가? 아니면 특정한 순서가 정해지지 않은 문자의 집합을 의미하는가?
    • src의 끝에 chars 가 여러 번 있으면 어떻게 되는가?
// 입력된 'src'의 'chars'라는 접두사와 접미사를 제거한다.
// 예: Strip('abba/a/ba', 'ab')은 '/a/'를 반환한다.
String Strip(String src, String chars) {
    ...
}
  • 이 예는 Strip()의 기능 전체를 보여준다.
  • 위에서 제기된 질문에 대답하지 않는, 지나치게 간단한 입출력 예는 좋지 않다.
// 입력된 'src'의 'chars'라는 접두사와 접미사를 제거한다.
// 예: Strip('ab', 'a')은 'b'를 반환한다.
String Strip(String src, String chars) {
    ...
}

6.6 요약

  • ‘it’이나 ‘this’같은 대명사가 여러 가지를 가리킬 수 있다면 사용하지 않는 것이 좋다.
  • 함수의 동작을 실제로 할 수 있는 한도 내에서 최대한 명확하게 설명하라
  • 신중하게 선택된 입/출력 예로 주석을 서술하라.
  • 코드가 가진 의도를 너무 자세한 내용이 아니라 높은 수준에서 개괄적으로 설명하라.

Comments