좋은 주석의 특징 9가지

MIT 교수 할 아벨슨은 이렇게 말했다.

 

프로그램은 사람들이 읽을 수 있도록 작성되어야 하며,
기계가 실행할 수 있도록 작성되어야 한다.

어쩌면 당연한 말일지 모른다.

하지만 그렇게 당연하고도 기본적이기에 중요하고,

우리의 마음속에 잘 새겨놓을 필요가 있는 말이라고 생각한다.

---

 

그리고 이 글의 핵심인 좋은 주석의 특징 9가지를 소개하겠다.

 

규칙1: 주석은 코드를 복제해서는 안된다.

- 말그대로 주석에 코드의 1차원적 해석만 달면 안된다는 것이다.

 

규칙2: 좋은 주석은 불분명한 코드를 변명하지 않는다.

- 주석으로 하여금 누가봐도 헷갈리거나 좋지 못한  코드를 감싸는 듯한 코드는 좋지 않다는 것이다.

 

규칙3: 명확한 주석을 쓸 수 없다면, 코드에 문제가 있을 수 있다.

-위와 같은 맥락으로 코드를 해석하기 어렵다는 뜻으로, 그럴바엔 명확하게 다시 쓰자.

 

규칙4: 의견은 혼란을 야기하는 것이 아니라 혼란을 없애야 한다.

-주석을 읽고 더 혼란스러워 진다면 안된다는 말이다.

 

규칙5: 주석에 unidiomatic 코드를 설명해야 한다.

-통상적 관념에서 어긋난다면 누구나 알아 볼수 있도록 설명하자.

 

규칙6: 복사된 코드의 원본 소스에 대한 링크를 제공해야한다.

-당연히 출처를 밝혀야 같은 팀원이나, 훗날 자신이 다시봐도 이해할 수 있다.

 

규칙7: 가장 도움이 될 외부 참조에 대한 링크를 포함해야한다.

-코드를 작성하면서 얻은 영감이나, 참조한 사이트가 있다면 적어두는 것이 좋다.

다른사람이 내 코드를 보고 이해하는 시간을 단축할 수 있다.

 

규칙8: 버그를 수정할 때 주석을 추가해야한다.

-코드를 고쳤다면, 필요하다면 수정한 부분을 명시해야 한다.

 

규칙9: 주석을 사용하여 불완전한 규현을 표시해야한다.

-내 코드의 결점을 공유하기가 꺼려지지만, 오히려 더 공유해서 보완할 수 있는 기회를 얻어야 한다.

 

 

---

 

우리는 코드로 문제해결을 할 것이고,

주석으로는 성장을 할 것이다.