노마드코더 | 클린코드 챌린지 (06~07 / 21)

/// <summary>
/// Nomad Coder - 클린코드 챌린지 - 06~07 / 21
/// @author         : CloudD
/// @last update  : 2025. 05. 29.
/// @update
///     - 2025. 05. 29 : 최초 작성. (4장. 주석)
/// </summary>

Chat GPT 가 생성한 '개발자의 독서' 이미지 #4

어제와 오늘은 4장 "주석" 을 읽었습니다.

책에서 나열한 '글자 값을 하는 주석' 몇 가지와 작가가 '나쁜 주석' 이라고 부르는 사례들을 읽고, 제가 느낀 점을 정리해 봅니다.

작가의 생각

작가는 4장의 시작에서, 자신이 가진 주석에 대한 생각을 풀어냅니다.

잘 달린 주석은 그 어떤 정보보다 유용하다. 

경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다. 

오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다.

주석을 엄격하게 관리하기 보다는, 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로 에너지를 쏟겠다. 

진실은 한 곳에만 존재한다. 바로 코드다.

또한, 가능하다면 주석을 쓰지 않는 편이 낫다고 말하며, 다음과 같은 이유를 제시합니다.

1. 주석은 나쁜 코드를 보완하지 못한다
   코드를 난장판으로 만들고 주석으로 설명하지 말고, 난장판을 치우는데 시간을 보내라.
2. 코드로 의도를 표현하라.
   주석으로 달려는 설명을 함수로 표현해도 충분하다.

글자 값을 한다고 생각하는 주석 몇 가지

1. 법적인 주석 : 라이선스, 저작권, 외부 문서 참조 등
2. 정보를 제공하는 주석 : 하지만, 네이밍을 변경하거나 별도의 클래스를 만드는 형태를 추천
3. 의도를 설명하는 주석
4. 의미를 명료하게 밝히는 주석
5. 결과를 경고하는 주석 : 예) 특정 테스트 케이스를 꺼야 하는 경우
6. TODO 주석 : 앞으로 할 일을 적어놓는 경우
7. 중요성을 강조하는 주석
8. 공개 API 에서 Javadocs

 

나쁜 주석들

1. 주절거리는 주석 : 특별한 이유 없이 의무감 또는 프로세스에서 하라고 하니까 마지못해 적은 주석
2. 같은 이야기를 중복하는 주석 :코드의 내용을 굳이 풀어 쓴 주석. 코드보다 부정확 할 가능성 있음.
3. 오해할 여지가 있는 주석
4. 의무적으로 다는 주석
5. 이력을 기록하는 주석 : 소스 관리 시스템에 맡길 것.
6. 있으나 마나 한 주석
7. 무서운 잡음 : 때로는 Javadocs 도 잡음
8. 함수나 변수로 표현할 수 있는 주석
9. 위치를 표시하는 주석 : 특정 영역에 배너처럼 다는 주석은 과하게 사용하면 일종의 잡음이 됨.
10. 닫는 괄호에 다는 주석 : 닫는 괄호에 주석을 달아야 겠다는 생각이 든다면 함수를 줄이려고 시도할 것.
11. 공로를 돌리거나 저자를 표시하는 주석 : 이 또한 소스 관리 시스템에 맡길 것.
12. 주석으로 처리한 코드 : 주석으로 처리된 코드는 독자가 코드의 사용 여부를 알 수 없게 만든다. 이 또한 소스 관리 시스템에 맡기고, 과감히 삭제할 것.
13. HTML 주석
14. 전역 정보 : 주석을 달아야 한다면 근처에 있는 코드만 기술할 것.
15. 너무 많은 정보 : 해당 코드의 역사나 관련 없는 정보를 장황하게 늘어놓지 말 것.
16. 모호한 관계 : 주석과 구문 사이의 관계가 명백하지 못하면 주석에 대한 설명을 요구하게 됨.
17. 함수 헤더 : 짧은 함수는 긴 설명이 필요없다. 주석으로 헤더를 추가하기 보다는 짧고 한 가지만 수행하며 이름을 잘 붙인 함수를 만들 것.
18. 비공개 코드에서 Javadocs : 공개하지 않을 코드라면 Javadocs 가 쓸모 없음.

소감

'나쁜 주석' 중에서 제가 자주 사용하는 유형이 있습니다.

5번 (이력 주석)과 11번 (저자 주석) 입니다.

팀 작업 중 누가 어떤 의도로 코드를 수정했는지 파악하기 어려워,
간단하게라도 주석을 적어달라고 요청한 적이 있습니다.

그런데 이 부분을 읽으며, 

'팀원 모두 시간에 쫓겨 의도를 알 수 없는 코드를 남기고 있던 것은 아닐까' 하는 생각이 들었습니다.

또 예전에 누군가가 '주석이 필요 없다고 하는 건 억지 아닌가.' 라고 말했던 기억이 떠올랐습니다.
그 때는 저도 '사람마다 다르게 생각할 수 있다.' 고 생각하며 지나쳤습니다.

사실, 저자는 주석을 무조건 없애자는 게 아니라 

'필요한 주석' 과 '불필요한 주석' 을 분명히 구분하고,

필요 없는 주석은 삭제하는 것이 맞다고 말하고 있습니다.

우리는 저자이니, 독자가 오해할 수 있는 여지를 남겨서는 안 됩니다.

저도 오늘 제 코드를 돌아보며, 오해의 소지가 있는 주석들을 점검해봐야겠습니다.