클린코드 4장 주석

좋은이름, 서술적인 이름의 연장선 격인 쳅터입니다.

저자는 시작하는 문단부터, 주석은 결코 선하지못하고, 기껏해야 필요악이라며 다소 강한 논조의 주장을 합니다.

그 이유는 주석이 거짓말- 잘못된 정보를 제공

하는경우가 많고, 그리고 또 주석이 할수있는것은 대부분 코드도 할수있는것이기 때문입니다.

하지만 사실, 책 내용을 살펴보면 이 쳅터의 중심주제는, 주석을 쓰지마라가 아닙니다.

오히려 꼭 필요한 곳에만 주석을 사용하라 에 가깝습니다.

저자가 주장하는 꼭 필요한 주석목록은 다음과 같습니다.

### 필요한 주석

1. 법적인주석

- 법적인 이유로 의무 기입해야 하는 주석

- 저작권정보나 소유권 정보

2. 정보를 제공하는 주석

3. 의도를 설명하는 주석

4. 의미를 명료하게 해주는 주석

- 직접 짠 로직이 아니라 외부라이브러리를 사용하는 경우에 이용

5. 결과를 경고하는 주석

6. TODO 주석

- 구현이 완료되지 않은 모듈에 남겨놓은 메모

7. 중요성을 강조하는 주석

- 특별히 강조해야 하는 포인트를 짚어줌

8. 공개 API의 주석

- 해당 API사용자에게 정보를 제공

이중에 절대적으로 필요한 주석, 좋은주석은 법적인주석 밖에없습니다.

주석의 종류가 상단에 나열된 분류중 하나라고해도, 그것은 부적절한 주석일 수 있습니다.

왜냐하면, 주석 자체의 위치가 이상하거나, 맥락을 비롯한 기타 정보가 부족하여, 설명의 기능을 성실히 수행하지못하면 그것이 바로 쓸데없는 주석이기 때문입니다.

좋은 주석이라면, 다른 자료를 참고하지않고 해당 주석만 읽어도 그 내용을 이해할 수있어야하며, 자신이 설명하는 대상(코드)에 붙어있어야합니다.

그리고 또 저자는 안좋은 주석에대한 예시도 많이보여주는데, 한번 읽어보고 반면교사로 삼을만한 내용인것 같습니다.

하지만, 좋은주석과 다르게 분류를 해서 정리까지 해놓을 필요는 없어보입니다.

왜냐하면 좋은 주석이라는것이 너무 명확하기 떄문입니다.

### 나는 주석을 어떻게 사용하고있지?

저는 프로그래밍 공부를 시작한지얼마안되어

이펙티브 타입스크립트 라는 책을 먼저 읽었습니다.

이 책에서도 주석을 사용하는것이 안좋다고 주장하는데요,

마찬가지로 주석이 거짓말- 잘못된 정보를 제공하기 때문이라고 합니다.

하지만 중심 논지는 조금다릅니다.

이펙티브 타입스크립트에서는 주석은 업데이트에 대한 의무가 없으므로 사용을 자제해야 한다고 말합니다 .

즉, 코드는 변화에 대응해야하므로, 로직이 수정되어야하는 상황에서는 반드시 수정이 되지만, 주석은 그렇지 않으므로, 업데이트가 안되거나 더뎌서, 코드에대한 제대로된 정보를 제공하지 못하게 된다는 것이죠.

이것은 아주 오래전에 작성된 블로그 글이, 현재 상황과는 맞지않는것과 같습니다.

.

### 나는 주석을 어떻게 쓰고있지?

저는 원래부터 당연히 특별한 설명이나 대우가 필요한 코드가 아니면 주석을 달지 않았습니다. 왜냐하면 주석을 작성하는것 자체가 노동이니까요.

그래서 처음 JSDOC / TSDOC 작성법을 익힐때 이후로는 거의 주석을 달지 않았습니다.

저자의 의견과 별개로,

지금 필요하다고 생각하는 주석으로는 다음 네가지 정도가 있습니다.

- 1. TO ADD 주석

- 다른부분이 구현되어야 추가가 가능한 코드

- 사실상 구현이 확정된 코드를 미리 구현해놓고 주석처리 해놓은것

- 2. 변경시 말씀해주세요 주석

- 수정하고싶으면 물어봐달라는 주석

-

3. TODO 주석

- 작업중에 생각 및 작업순서를 정리하려고 작성하는 계획 주석

-

4. 정보주석

- 코드가 다루는 복잡한 도메인 지식이나 알고리즘을 설명하기 위한 주석

이중에 3번주석: TODO주석은 공부를 할수록 줄어가고있습니다.

요즈음 타입스크립트와 객체지향을 사용하며 프로그래밍을 하면서 계획 작성 또한 코드로 하게 되었거든요.

무언가를 만들기전에 항상 타입 /인터페이스 / 추상클래스등을 만들고있는데요. 그것들이 곧 그것이 곧 앞으로 구현할 코드에 대한 명세이자 계획이 되고 있습니다.

테스트코드 까지 작성하게 되면 계획에 관련된 주석은

아예 작성을 하지 않을 것 같습니다.

또, 4번 정보를 설명하는주석은 필요하다고 생각하면서도

아직은 작성해본적이 없습니다.

지금까지 제가 작성했던 프로그램은 간단하고 유명한 웹기술들을 활용했습니다. 그래서 웹 개발자가 제 코드를 읽는다면, 굳이 지식에대한 부연설명이 필요없었죠.

그런데 제가 깊은 이해와 학습이 필요한 특정 도메인지식 혹은 알고리즘을 사용하는 프로그램을 만들게된다면,

복잡한내용을 다른 개발자들에게 명쾌하게 설명하는 주석을 작성하는것이

꼭 필요한 업무중 하나가 될거라 생각합니다.