반응형
PART I. 표면적 수준에서의 개선
5장. 주석에 담아야 하는 대상
★ 주석의 목적은 코드를 읽는 사람이 코드를 작성한 사람만큼 코드를 잘 이해하게 돕는 데 있다.
__01. 설명하지 말아야 하는 것
★ 코드에서 빠르게 유추할 수 있는 내용은 주석으로 달지 말라.
- 설명 자체를 위한 설명을 달지 말라. 주석을 달아야하겠다면 파악하기 어려운 세부사항을 적는것이 좋다.
- 나쁜 이름에 주석을 달지 마라. 대신 이름을 고쳐라. 좋은 코드 > 나쁜 코드 + 좋은 주석
__02. 생각을 기록하라
- 코드를 짜면서 의도한 바나 깨달은 바를 주석으로 기록하라.
- 상수가 무엇을 하는지, 그것이 왜 특정한 값을 갖게 되었는지에 대한 내용을 기록해둬라.
- 코드에 있는 결함을 설명하라. 코드에 부족한 점이 있는건 당연하고, 당장 그것을 고칠 시간이 없을때도 많다.
- 코드의 어떠한 내용을 훗날 수정할 것이라는 생각이 들면 이를 주석으로 작성하는 걸 당연하게 받아들여라.
- 코드에 개선해야 할 점이 있다고 생각된다면 이를 주석으로 기록하라. 다음은 이를 위해 자주 쓰이는 표시들이다.
- TODO : 아직 하지 않은 일
- FIXME : 오작동을 일으킨다고 알려진 코드.
- HACK : 아름답지 않은 해결책
- XXX : 위험! 여기 큰 문제가 있다.
__03. 코드를 읽는 사람의 입장이 되어라
- 코드를 처음으로 읽는 외부인의 입장이 되어보라.- 나올 것 같은 질문 예측하기 : 누군가가 코드를 읽었을 때 할법한 질문의 답변을 주석으로 달아라.
- 사람들이 쉽게 빠질 것 같은 함정을 경고하라 : 코드를 쓰다가 생길수 있는 문제점을 미리 예측해서 주석으로 달아라.
- '큰 그림'에 대한 주석 : 특정 코드가 상위 수준의 문제와 어떻게 연결되어 있는지를 주석으로 달아라.
- 이는 함수 내부에서 코드의 목적을 설명하는 식으로도 적용될 수 있다.
- 사람들이 코드를 쉽게 읽을 수 있게 도와주는 내용이라면 그것이 무엇이든지 적어두는 것이 좋다.
__04. 마지막 고찰 - 글 쓰는 두려움을 떨쳐내라
- 그냥 떠오르는 생각이라도 써있는 것이 아무것도 안 써있는 것보다는 좋다.
- 떠오른 생각을 적은 주석의 표현들을 좀 더 구체적인 표현으로 바꾸다보면 사람들이 읽기 편한 주석을 작성할 수 있다.
반응형