클린코드 4장 : 주석

잘 달린 주석은 그 어떤 정보보다 유용하다. 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼트려 해악을 미친다.

저자는 주석을 써야할 때가 분명 있지만, 가능한한 줄이는 걸 권장한다. 특히, 오래된 주석, 잘못된 주석을 경계하라한다.

 

주석은 나쁜 코드를 보완하지 못한다.

- 코드가 읽기 힘들고 짜임새가 나쁘다면, 주석을 달지 말고 코드를 정리해라.

- 주석이 아니라 코드로 주석을 표현해라

 

좋은 주석 

- 법적인/ 정책상 필요한 주석 : 이는 코드에서 나타날 수 없어서 최상단에 쓰면 좋다.

- 정보 제공 주석 : 날짜형식 등 부가정보를 전달할 때 쓰면 좋다.

- 의도를 설명하는 주석 : 알고리즘을 왜 이렇게 짰는 지 등 로직의 의도를 설명해야할 때 쓰면 좋다.

- 의미를 명료하게 설명하는 주석 : 라이브러리 등의 제한으로 코드를 깔끔하게 짤 수 없다면 차선책으로 주석을 이용하여 설명하면 좋다.

- 결과를 경고하는 주석 / 중요성을 강조하는 주석 : 시간제한 등 결과를 경고해야할 때, 실행할 때 문제가 되는 점을 경고할 때 등 함수의 필수사항을 강조 또는 경고하는 주석

- TODO 주석 : 앞으로 해야할 일을 남길 때 쓰면 좋다.

※ 하지만, 저자는 이런 주석도 최소화하고 필수적일때만 쓰기를 바란다.

 

나쁜 주석

- 혼잣말 주석 / 중복 주석 / 의미 없는 주석 / 의무적인 주석 / (코드) 위치 표시 주석 : 불필요한 정보를 남기지 마라

- 오해의 여지가 있는 주석 / 의미가 모호한 주석 : 오해할 수 있고 의미가 모호한 주석은 오히려 악영향을 미친다. 쓰지 말자

- 너무 많은 정보를 담은 주석 : 읽기 불편한 정보를 억지로 많이 넣은 주석은 있으나 마나하다.

- 전역 정보를 담은 주석 : 각 모듈에서 정보를 표현하자. 전역은 전역 관리하는 데서 한 번만 서술하자.

- 저자를 표시하는 주석 / 코드 수정 이력 주석 : 버전 관리 프로그램이 다 해준다. 쓰지말자.

- 주석 처리된 코드 : 남의 주석은 삭제하기 너무 힘들다. 무조건 지워라. 필요한 정보는 버전 관리 프로그램이 기록해준다.

 

느낀 점

- 개인적으로 다른 사람 코드 읽을 때, 의도 설명하는 주석이 참 좋았다. 특히, Type이 의미하는 바가 명확해지니 정말 좋았다.

- Todo 주석이 생각보다 굉장히 좋다. 어디까지 구현되어있는가가 명확히 보인다.

- 주석 처리된 코드가 생각보다 굉장히 껄끄러웠는데, 앞으로 과감하게 지워야겠다.