주석의 딜레마
- 주석은 때때로 거짓말을 한다. (작성된지 오래일수록 더욱 그렇다.)
- 부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다.
- 주석을 쓰기보다 코드를 더욱 깔끔하게 하자.
주석은 나쁜 코드를 보완하지 못한다.
- 표현력이 풍부하고 깔끔하며 주석이 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
좋은 주석
법적인 주석 : 저작권 정보와 소유권 정보이다.정보 제공 주석 : 기본적인 정보를 주석으로 제공하면 편하다.의도를 설명하는 주석 : 때때로 주석은 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명한다.의미를 명료하게 밝히는 주석 : 때때로 모호한 인수나 반환값은 그 의미를 읽기 좋게 표현한다.결과를 경고하는 주석 : 때로 다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용한다.TODO 주석 : 앞으로의 할 일을 주석으로 남겨두면 편하다.중요성을 강조하는 주석 : 자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해서도 주석을 사용한다.
나쁜 주석
주절거리는 주석 : 의미없는 문장은 필요없다.같은 이야기를 중복하는 주석 : 쓸모없고 중복된 주석은 오히려 보기 힘들다.오해할 여지가 있는 주석 : 의도는 좋으나 문맥이 알맞지 않아 이해하기 모호한 주석이다.위치를 표시하는 주석 : 일반적으로 가독성을 낮춘다.닫는 괄호의 주석 : 중첩이 심한 함수라면 의미 있을지 모르지만, 작고 캡슐화된 함수에는 잡음일 뿐이다.공로를 돌리거나 저자를 표시하는 주석 : 이런 주석은 시간이 지날수록 쓸모가 없을 경우가 크다.주석으로 처리한 코드 : 이전 내용을 주석으로 처리한 코드는 좋지 못하다.HTML 주석 : 주석에 HTML 태그를 삽입하는 것은 프로그래머가 아닌 도구가 책임져야 하는 것이며, 의미가 없다.전역 정보 주석 : 주석은 근처에 있는 코드에만 기술하는 것이 좋다. 전역 정보가 다른 프로그램에서는 알맞지 않은 주석이 될 수 있다.너무 많은 정보 : 너무 많은 정보를 바탕으로 작성한 주석은 오히려 가독성을 떨어트린다.