Clean Code - 주석

이상한 행동 하지말라고 단거야!

Clean Code : 주석

 

코딩을 배우는 첫날부터 배우는 게 주석이다

 

사실 입문자들에겐 그저 나중에 자신이 봐도 이해할 수 있도록 설명하는 정도...

혹은 자신의 코드를 볼 누군가를 위한 힌트 정도이다

(실제로 주석을 이쁘게 잘달아야 한다고 가르친다!)

 

 

근데 그거 아는가?

흔히 우리가 어떤 책이나 논문을 읽을 때

작성자만 아는 얘기를 써놓고 거기에

주석이 달려 있으면

보기가 굉장히 불편해진다(나만 그런가)

 

잘된 코딩은 주석 없이 언어만 읽어도 자연스레 이해가 되어야 한다

(글과 마찬가지다)

 

물론 좋은 주석도 있고

실제로 많은 훌륭한 개발자들도 주석을 조금씩 사용한다

언제 어떻게 사용할지 알아보자

 

---

 

'우리는 코드로 의도를 표현할 방법을 찾지 못해 주석을 사용한다'

 

코드는 계속 변한다

프로그래머가 주석을 유지 보수하는데 드는 비용도 크고

실제로 그마저도 잘 이루어지지도 않는다

 

우리는 최대한 주석이 필요 없도록 개발해야 한다

 

// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if (employee.flags & HOURLY_FLAG) && (employee.age > 65)

if employee.isEligibleForFullBenefits()

위의 두 가지 중, 주석이 없는 쪽이 더 깔끔하다

 

 

그렇다면 좋은 주석은?

---

좋은 주석

1. 법적인 주석

소스 파일 첫머리에 저작권 정보와 소유권 정보

//Copyright (C) ~~~

 

모든 조항, 조건을 열거하는 대신 표준 라이센스나 외부 문서를 참조해도 괜찮다

 

 

2. 정보를 제공하는 주석

// kk:mm:ss EEE, MMM dd, yyyy 형식

정규표현식이 시각과 날짜를 뜻한다고 설명하는 예시

 

사실 이것도 시각과 날짜를 변환하는 클래스를 만들어 두는 게 더 좋다

 

3. 의도를 설명하는 주석

쓰레드를 사용한 이유

쓰레드 개수를 정한 이유

등등

 

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

인수나 반환 값이 표준 라이브러리거나 변경하지 못하는 경우

주석이 명료할 수 있다

 

5. 결과를 경고하는 주석

예를 들어 특정 테스트 케이스를 꺼야 하는 이유를 설명

// 여유 시간이 충분하지 않다면 실행하지 마십시오.

 

6. TODO

함수를 구현하지 않은 이유, 미래 모습을 설명

누군가에게 부탁 등

 

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

자칫 대수롭지 않다고 여겨질 무언가의 중요성을 강조

 

8. Open API에서 Javadocs

잘 정리된 API와 docs는 유용하다

 

 

그렇다면 나쁜 주석은?

 

---

나쁜 주석

1. 주절 거리는 주석

주석을 달기로 했다면 충분한 시간을 들여 최고의 주석을 달자

이해가 안 되어 다른 모듈까지 뒤져야 하는 주석은 잘못된 주석이다

 

2. 이야기를 중복하는 주석

코드 내용을 그대로 설명하는 주석은 필요 없다(변수 이름 포함)

실제로 코드보다 부정확해 독자가 대충 넘어가게 만든다

(엔진 후드를 열어볼 필요가 없다며 아양 떠는 중고차 딜러와 비슷)

 

3. 오해할 여지가 있는 주석

어느 프로그래머가 실수할 여지를 만드는 주석은 피해라

 

4. 의무적으로 다는 주석

모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석다

(하지만 실제로는 다들 한다...)

 

5. 이력을 기록하는 주석

모듈을 편집할 때마다 주석을 추가하는 행위

소스 코드 관리 시스템이 없던 시절에는 바람직했다

 

6. 필요 없는 주석

지나친 참견의 주석은 개발자가 주석을 무시하는 습관이 들게 한다

 

7. 함수나 변수로 표현할 수 있다면 주석을 달지 마라

우리는 프로그래머다 친절한 주석에 의존하기보단

코드를 읽고 이해할 수 있는 편이 정확하고 문제가 없다

 

8. 주석으로 처리한 코드

주석으로 처리된 코드는 지우기가 주저된다

이유가 있을 거 같아서...

 

옛날에는 유용했으나 현재에는 소스 코드 관리 시스템이 있다

그냥 삭제하라

 

9. 전역 정보

주석을 단다면 근처의 코드만 기술하라

 

10. 너무 많은 정보

TMI 하지 마라...(뜨끔)

흥미로운 역사, 과도한 설명은 불필요하다

 

11. 이해하지 못하는 주석

당연히 누군가 처음 보고 이해할 수 없는 주석은 필요가 없다

 

 

---

이번 장은 주석에 관한 내용이라 명심할 부분만 정리해두었다

(중복하지 말라고 하면서 이 책에서는 중복하는 내용이 많더라...)

 

개인적으로 괜히 찔리는 부분이 많았고

학생 때 소스관리 시스템이 나오기 전인 옛날 코드들을 많이 본 게

이러한 습관이 들게 만든 원인인 것 같다