읽기 좋은 코드가 좋은 코드다

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

 

📌 주석을 간결하게 하라

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

- 주석을 왜 세줄이나 쓰나?

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

- 주석이 세줄 필요할 때도 있지만 이 경우는 아니다.

 

📌 모호한 대명사는 피하라

- it (x) > the data (o)

 

📌 엉터리 문장을 다듬어라

❌ # 이 URL을 전에 이미 방문했는지에 따라서 다른 우선순위를 부여한다.
⭕ # 전에 방문하지 않은 URL에 높은 우선순위를 부여하라.

 

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

// 이 파일에 담긴 줄 수를 반환한다.
int CountLines(string filename)

- " " 은 줄 수가 0인가 1인가?

- "helllo"는 줄 수가 0인가 1인가?

 

이런 의문과 같이 쓰여진 주석은 명확하지 않음.

가장 간단한 구현은 단순히 개행문자(\n)를 세는 것.

 

⭕ //파일 안에 새 줄을 나타내는 바이트('\n')가 몇 개 있는지 센다.

 

📌 구체적인 용법을 설명해주는 입/출력 예를 사용하라.

// 입력된 'src'의 'chars'라는 접두사와 접미사를 제거한다.
String Strip(String src, String chars)

? 왜 명확하지 않은지?

- chars가 제거되어야 하는 정확한 부분 문자열을 의미하는가?

- 특정한 순서가 정해지지 않은 문자의 집합을 의미하는가?

- src의 끝에 chars가 여러 번 있으면 어떻게 되는가?

 

⭕ // 예: Strip("abba/a/ba", "ab")은 "/a/"를 반환한다.

 

 

📌 코드의 의도를 명시하라

// 리스트를 역순으로 반복한다.
 for (list<Product> ~~~~

- 코드가 수행하는 동작을 문자 그대로 설명하지 말고 의도를 명시하기.

⭕ // 각 가격을 높은 값에서 낮은 값 순으로 나타낸다

 

 

 

 

- 함수의 동작을 실제로 할 수 있는 한도 내에서 최대한 명확하게 설명.

- 신중하게 선택된 입/출력 예로 주석을 서술

- 코드가 가진 의도를 너무 자세한 내용이 아니라 높은 수준에서 개괄적으로 설명

- 같은 줄에 있는 주석으로 (ex. Function(/*arg = */ ...)) 의미가 불분명한 함수의 인수를 설명

- 많은 의미를 함축하는 단어로 주석을 간단하게 만들기.