5. 주석에 담아야 하는 대상

이 글은 읽기 좋은 코드가 좋은 코드다(더스틴 보즈웰, 트레버 파우커 지음 / 임백준 옮김 / 한빛미디어) 를 읽고 내용을 정리한 글입니다.

<<주석의 목적: 코드를 읽는 사람이 코드를 작성한 사람만큼 코드를 잘 이해하게 도와준다>>

 

1. 설명하지 말아야 하는 것

-> 코드에서 빠르게 유추할 수 있는 내용은 주석으로 달지 않는다.

-> 주석을 달 때는 실제 주석이 도움될지를 고민해보고 달아라.

-> 이름이 애매하다면 주석으로 설명할 것이 아니라, 이름 자체를 수정해야한다.

-> 좋은 코드 > 나쁜 코드 + 주석

 

2. 생각을 기록하라

-> 코드를 짜면서 얻게된 중요한 통찰을 주석으로 기록하여, 읽는이가 헷갈리지 않도록 하라

TODO	해야할 일
FIXME	오동작을 일으킨다고 알려진 코드
HACK	좋지 않은 해결책
XXX	위험!
TestMate	ESC

 

-> 상수에도 주석을 붙이면 의미가 더 뚜렷해진다.

 

3. 코드를 읽는 사람의 입장이 되어라

-> 코드를 읽는 사람이 궁금해할만한 질문을 예측한다.

-> 사람들이 실수할 수도 있는 부분 또한 주석으로 달아둔다.

-> 함수의 기능을 요약해서 앞에 달아주는 것도 좋다.

 

4. 글쓰는 두려움을 떨쳐내라

-> 좋은 주석을 창작하기 위해 시간 쓰는 것을 아까워하지 마라.

-> 마음에 떠오르는 생각을 우선 적고, 수정하면 쉽다.

 

5. 결론

-> 설명하지 말아야 하는 것

1) 코드 자체에서 재빨리 도출될 수 있는 사실
2) 나쁜 함수명과 같이 나쁘게 작성된 코드를 보정하려고 '애쓰는 주석'

 

-> 설명해야 하는 것

1) 코드가 특정한 방식으로 작성된 이유를 설명해주는 내용
2) 코드에 담긴 결함(TODO or XXX 사용)
3) 어떤 상수가 특정한 값을 갖게 된 '사연'