PART I. 표면적 수준에서의 개선
6장 명확하고 간결한 주석 달기
- 주석은 높은 '정보 대 공간' 비율을 갖춰야 한다.
__01. 주석을 간결하게 하라
- 짧게 줄여도 정보를 충분히 전달할 수 있다면 주석을 짧게 줄여라.
__02. 모호한 대명사는 피하라
- 모호한 대명사는 원래 명사로 고치거나, 의미가 명확해지도록 문장을 고쳐라.
__03. 엉터리 문장을 다듬어라
- 주석을 명확하게 하는 작업과 간결하게 하는 작업은 대부분 한꺼번에 이루어진다.
__04. 함수의 동작을 명확하게 설명하라
- 애매한 단어를 사용하지 말고 구현한 방식을 명확하게 설명하는 것이 좋다.
__5. 구체적인 용법을 설명해주는 입/출력 예를 사용하라
- 주석을 작성하는 데 신중하게 선택된 입/출력 예는 천 마디 말보다 위력적이다.
- 모든 동작을 표현할 수 있는 입/출력 예를 주석으로 사용하라.
__6. 코드의 의도를 명시하라
- 이러한 주석은 코드가 의도와 다르게 작동하는지 확인하기 좋다.
__7. 이름을 가진 파라미터(Named Function Parameter) 주석
- 뜻이 잘 들어나는 이름을 지을 수 없거나 값을 전달할 때 그 값의 의미를 알기가 힘들다면 값의 앞에 주석을 달아라.
ex) connect(10,false); 를 connect(/*timout_ms = */ 10, /* use_encryption = */ false); 로.
__8. 정보 축약형 단어를 사용하라
- 지속적으로 반복되는 문제에 대해서는 이를 표현하기 위한 관용적 표현이 만들어져 있는 경우가 많다. 이를 찾아보고 활용하라.
ex) '경험적인(heuristic)', '주먹구구식(brute_force)', '순진한 해법(native solution)' 등