[1부 코드와 마주보기] Chapter5 가벼운 코멘트

코멘트(comment: 주석)는 의견과 아주 비슷합니다. 코멘트를 다는 것은 자유지만, 그렇다고 해서 반드시 그 내용이 옳은 것은 아니다.

코멘트는 우리의 생명선이고, 촉진제이고, 코드 전체를 통한 길잡이이다.

 

코멘트를 잘 다는 것은 위험한 코드를 예방하는 전략 중 하나이다.

 

코멘트란 무엇인가?

생각하는 것보다 더 철학적인 것

문법적으로 코멘트는컴파일러가 무시하는 소스 블록        

코멘트는 컴퓨터가 겨냥하는 것이 아니라 프로그램을 읽는 사람을 겨냥한다.

우리는 책임 있는 프로그래머로서 코멘트를 잘 달아야 할 의무가 있다.

 

얼마나 많은 코멘트가 필요할까?

우리는 코멘트의 양이 아니라 질에 초점을 맞출 필요가 있다.

지나치게 많은 코멘트는 코드를 뒤죽박죽으로 만든다.

수 톤의 코멘트로 떠받칠 필요가 없는 코드를 작성하는 데 시간을 투자하자

 

코멘트 안에는 무엇이 들어갈까?

어떻게가 아니라 왜를 기술하라

코드의 의도를 전달

훌륭한 코멘트는 어떻게가 아니라 왜를 설명한다

코드를 묘사하지 마라

코멘트가 없으면 이해할 수 없을 정도로 복잡한 알고리즘을 문서화하는 경우가 아니라면 코드를 자연어로 풀어쓰는 고생을 할 필요 없다

코드와 중복되는 내용을 코멘트로 다시 쓰지 말자

코드를 대신하지 마라

유용성을 유지하라

의외의 것을 기록하라: 유별난 코드, 예기치 못한 코드, 의외의 코드는 코멘트를 이용해서 설명

진실을 말하라: 거짓은 코멘트가 아니다

가치 있게 만들어라

명료하게 만들어라

알기 쉽게 만들어라

주의를 흩뜨리지 마라 (사용하지 말자)

코멘트는 주변의 코드를 잘 보이게 만드는 역할을 해야 한다.

과거: 예전에 무언가를 어떻게 했었다는 기록은 남길 필요가 없다.

불필요한 코드: C에서는 #ifdef 0 … #endif 를 사용하자

ASCII 기교

블록의 끝: //end if (a<1) => "모든"이라고 써있으니 어느 정도는 되는 건가?

실무에서는

나쁜 코드는 문서화하지 말고 다시 작성하자

코멘트의 미학

일관성

모든 코멘트는 명료하고 일관성있게

뚜렷한 블록 코멘트

최소한 코멘트에 있는 텍스트가 들쑥날쑥하지 않게 줄을 맞추자

코멘트 들여쓰기

코멘트를 주변 코드와 동일 수준으로 들여 쓰자

코드 읽기 도와주기

코드의 위쪽에 쓰자

방파제 코멘트

잘 선택된 방파제 코멘트는 파일의 빠른 내비게이션을 도와준다.

플래그

코멘트는 인라인 플래그(inline flag)로 사용

//XXX, //FIXME, //TODO

파일 헤더 코멘트

소스 파일은 모두 파일의 내용을 설명하는 코멘트 블록으로 시작해야 한다.

파일 헤더에는 작성자, 수정자, 최종 수정일자와 같이 쉽게 뒤쳐질 수 있는 정보는 포함하지 말 것.

코멘트 가지고 일하기

루틴 작성 도와주기

먼저 코멘트로 루틴의 구조를 만들고, 그 다음에 코멘트의 각 행 아래 코드로 채우는 것 : 해보자!!!!

숙련되면 코멘트와 소스를 동시에 작성한다

버그를 고치는 공지

코멘트는 과거가 아니라 현재 속에 살아야 한다. 코드가 바뀌었다거나 예전에 뭐가 어땠었다는 기술 할 필요 없다.

코멘트의 부패

코드를 변경할 때 그 주변에 있는 코멘트도 모두 유지보수 하자

코드를 코멘트로 막을 경우 이유를 설명하는 메모를 남겨놓거나 코드를 지우자. 이건 SVN이 다 해준다

공허한 코멘트가 뭐지?

 

좋은 프로그래머는…

정말 훌륭한 소량의 코멘트를 작성하려고 노력한다.

왜에 대해서 설명하는 코멘트를 작성한다.

과도한 코멘트가 아니라 좋은 코드의 작성에 집중한다.

의미 있는 유용한 코멘트를 작성한다.