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

이 글은 읽기 좋은 코드가 좋은 코드다(더스틴 보즈웰, 트레버 파우커 지음 / 임백준 옮김 / 한빛미디어) 를 읽고 내용을 정리한 글입니다.

<<주석은 높은 "정보 대 공간" 비율을 가져야 한다!>>

 

1. 주석을 간결하게 하라

// **bad**

//int는 CategoryType이다.
//내부 페어의 첫 번째 float은 'score'다
//두 번째는 'weight'이다.
typedef hash_map<int, pair<float, float>> ScoreMap;

// ----------------------------

// **good**

// CategoryType -> (score, weight)
typedef hash_map<int, pair<float, float>> ScoreMap;

 

2. 모호한 대명사를 피하라

-> 'it', 'that', 'this'를 피하고, 명확한 대상을 적어라

 

3. 엉터리 문장을 다듬어라

-> 안좋은 예: "이 URL을 전에 방문했는지에 따라서 다른 우선순위를 부여한다." 

-> 좋은 예: "전에 방문하지 않은 URL에 높은 우선순위를 부여한다."

 

4. 함수의 동작을 명확하게 설명한다.

-> 안좋은 예: "이 파일에 담긴 줄 수를 반환한다."

-> 좋은 예: "파일 안에 새 줄을 나타내는 바이트('\n')이 몇 개 있는지 센다."

 

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

-> 안좋은 예: "입력된 'src'의 'chars'라는 접두사와 접미사를 제거한다."

-> 좋은 예: "예: Strip('abba/a/ba', 'ab')은 '/a/'를 반환한다."

-> 너무 단순한 케이스는 도움이 되지 않는다.

 

6. 코드의 의도를 명시하라

-> 프로그램이 수행하는 동작을 코드 그대로가 아닌, 구현 의도에 맞춰 작성하라.

 

7. 이름을 가진 함수 파라미터(Named Function Parameter) 주석

def Connect(timeout, use_encryption): ...

# **bad**
Connect(10, false)

# **good**
Connect(timeout = 10, use_encryption = False)

 

8. 정보 축약형 단어를 사용하라

-> 기능에 대해 지나치가 풀어쓰기 보다 보편적인 단어나 관용구를 사용해 축약 설명하라.