주석

진실은 한 곳에만 존재한다.
바로 코드다.
코드만이 자기가 하는 일을 진실되게 말한다. 코드만이 정확한 정보를 제공하는 유일한 출처다.
그러므로 우리는 주석을 가능한 줄이도록 꾸준히 노력해야 한다.
_클린코드, 4장 주석, 69p

클린코드를 보다 공감하는 부분이 생겨 작성해보려고 한다.

 

백엔드 개발자분과 swagger를 통해 소통하는 프로젝트였는데, 서버로부터 오는 내용과 api spec간의 차이가 발생해 tslint에러가 발생하는 문제로 난처한적이있었다.

 

이러한 문제가 발생하게 된 이유는 백엔드에서 api spec 관리를 커멘트기반의 swagger generation을 도입하고 있었고 ( B  )

backend code generation <- swagger json -> frontend code generation  --- ( A )
backend comment -> swagger json -> frontend code generation  ---------- ( B )

이러한 구조는 코드 구현이 달라졌을때 주석을 수정하는것을 깜빡하는 휴먼에러가 생겼을때 문제를 야기했다.

물론 코드를 수정했을때 주석을 바꾸는 프로세스를 철저히 지키면 문제없겠지만, 그건 누군가를 blame하게 되기만하지, 좋은 구조라고 생각들지 않는다.

 

코드는 언어(language)를 통해 작성된 문서(document)라는것이 본질이라 생각한다.

 

우리가 글을 쓸때 맥락에 필요하다면, 본문에 설명을 녹이지 주석을 쓰진 않는다. 코드도 이와 같다고 본다. 

이해하기 힘들다면, 사용하는 변수명, 구조를 고민해보고, 바꿔야한다고 생각한다. 코드의 맥락과 관련없는 법적인 문제, 혹은 규칙(컨벤션)과 관련된게 아니라면, 주석을 쓰는것보다 이해하기 편한 구조의 답은 항상 있을것이다.

 

내가 생각하는 주석을 쓰는 좋은 부분은 TODO : 정도 라고 본다.

 

VSCode extension - Todo Tree (https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree)

TODO는 나처럼 티켓관리에 부족한 사람에게 다른일에 매몰되어버리는 일을 막아 줄 수 있는 좋은 방법이라 생각하고 대부분의 IDE에서 지원하는 기능이니 활용하는걸 강추한다.