•
주석의 목적은 코드를 읽는 사람이 코드를 작성한 사람만큼 잘 이해하게 돕는 데 있다.
•
이 장에서는 머릿속에 있는 정보 중 어떤 정보를 언제 적어야 하는 가에 대해 보여줄 것이다.
◦
설명하지 말아야 하는 것
◦
코딩을 수행하면서 머릿속에 있는 정보를 기록하기
◦
코드를 읽는 사람의 입장에서 필요한 정보가 무엇인지 유추하기
설명하지 말아야 하는 것
•
주석은 코드에서 설명할 수 없는 부분을 설명해야 한다. 코드만 보고 빠르게 유추 가능한 내용을 설명하는 주석은 가치가 없는 주석이다.
•
무가치한 주석을 피하기 위한 지침은 다음과 같다.
◦
설명 자체를 위한 설명을 달지 마라.
◦
나쁜 이름에 주석을 달지 말고 이름을 고쳐라.
•
좋은 코드가 나쁜 코드와 좋은 주석을 합친 것보다 가독성이 더 낫다.
생각을 기록하라
•
좋은 주석은 단순히 자신의 관점을 작성해두는 것만으로도 탄생할 수 있다. 즉 코딩할 때 중요하게 생각한 내용을 기록하면 된다.
•
좋은 주석을 작성하기 위한 지침은 다음과 같다.
◦
감독의 설명을 포함하라.
◦
코드에 있는 결함을 설명하라.
▪
todo를 사용해 개선점이나 수정 사항을 기록해두는 것이 좋다.
▪
todo 외에도 fixme, hack, xxx, textmate 같은 표시가 있다.
◦
상수에 대한 설명을 추가하라.
▪
상수명으로 충분히 설명되지 않는 매직넘버는 주석을 추가하는 것이 좋다.
코드를 읽는 사람의 입장이 되어라.
•
좋은 코드를 작성하는 방법 중 하나는 우리의 도메인에 익숙하지 않은 외부인이 코드를 처음봤을 때의 관점에서 보는 것이다.
•
이 기법은 주석을 추가하기 위한 부분을 찾을 때 특히 유용하다.
◦
나올 것 같은 질문 예측하기
▪
내가 작성한 코드를 누군가 읽었을때, 이게 무슨 코드일까? 하는 부분에 주석을 달아라.
◦
사람들이 쉽게 빠질 것 같은 함정을 경고하라.
▪
내가 작성한 코드에 사이드 이펙트가 존재한다면 이를 주석으로 충분히 경고해두는 것도 좋다.
◦
‘큰 그림’에 대한 주석
▪
상세하고 공식적인 문서를 작성할 필요가 없다. 각 계층에 적절히 추상화된 내용을 주석으로 추가해두기만 해도 충분하다.
◦
요약 주석
▪
특정한 코드 블록이 무언가를 해낼 때, 이에 대해 개략적인 설명을 주석으로 다는 것도 좋다.
마지막 고찰 - 글 쓰는 두려움을 떨쳐내라
•
프로그래머들은 좋은 주석을 만들기 위해 시간을 보내는 것을 두려워한다. 아깝기 때문이다.
•
너무 두려워하지 말고 다음과 같은 순서를 따라 주석을 일단 써보고 점차 수정한다면 적은 시간을 들이고도 적절히 유용한 주석을 작성하는 것에 도움이 될 것이다.
◦
마음에 떠오르는 생각을 일단 적는다.
◦
주석을 읽고 무엇인 개선되어야 하는지 확인한다.
◦
개선한다.
요약
•
주석을 다는 목적은 코드를 작성하는 사람의 의도를 읽는 사람에게 충분히 전달하기 위함이다.
•
설명하지 말아야하는 주석의 내용은 다음과 같다.
◦
코드 자체에서 빠르게 도출될 수 있는 정보
◦
나쁜 함수명과 같이 본질적인 문제가 메소드에 있는 경우
•
기록해야 하는 주석의 내용은 다음과 같다.
◦
코드가 특정한 방식으로 작성된 이유를 설명해주는 이유
◦
코드에 담긴 결함
◦
어떤 상수가 특정한 값을 갖게 된 계기
•
외부인의 관점에서 본다면 어느 부분에서 주석이 필요한지 조금이나마 더 명확해질 것이다.
◦
코드를 읽는 사람이 자기가 작성한 코드의 어느 부분을 보고 뭐라고?라는 생각을 할지 예측해보자.
◦
평범한 사람이 예상하기 힘든 특이한 동작인지 생각해보자.
◦
파일이나 클래스 수준 주석에서 큰 그림을 설명하고 각 멤버들이 어떻게 작동하는지 설명해보자.
