클린 코드 4장 - 주석

나쁜 코드에 주석을 달지 마라. 새로 짜라. (68p)⭐️⭐️⭐️

• 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다.
• 주석을 사용하는 이유는 프로그래밍 언어로 풍부하게 표현할 수 있는 능력이 부족하기 때문이다. 따라서 주석은 코드로 개인의 의도를 표현하기에 실패했을 때 사용한다.
• 주석이 필요한 상황이 생긴다면 주석 대신 코드로 의도를 표현할 방법이 없는지 고민해보자.
• 주석은 오래될 수록 코드에서 멀어진다. 개발자들이 주석을 유지하고 보수하지 않기 때문이다.
• 코드만이 정확한 정보를 제공하는 유일한 출처다. 그러므로 우리는 주석을 가능한 줄이도록 노력해야 한다.

주석은 나쁜 코드를 보완하지 못한다. (69p)

• 코드에 주석을 추가하는 이유는 코드 품질이 나쁘기 때문이다 😭
• 주석을 달아야겠다 (X) 코드를 정리해야지 (O)
• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.

코드로 의도를 표현하라 (70p)

• 주석을 사용할 생각하지 말고 코드로 의도를 표현해야 한다.
• 많은 경우 “주석으로 달려는 설명을 함수로 만들어 표현”하면 된다. ⭐️⭐️

좋은 주석 (70p)

• 어떤 주석은 필요하긴 하다. 하지만 가장 좋은 건 주석을 달지 않는 것이다.

1. 법적인 주석

• 주석으로 들어가는 저작권 정보와 소유권 정보는 타당함

2. 정보를 제공하는 주석

• 반환할 값을 설명해주는 주석, 코드에서 사용한 정규표현식이 무엇을 뜻하는지 등이 있음. 그러나 가능하다면 주석을 사용하지 말고 클래스나 함수 이름에 정보를 담는 편이 더 좋다.

3. 의도를 설명하는 주석

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

5. 결과를 경고하는 주석

• 다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용한다. (이건 좀 괜찮은 주석 같음)

// 해당 코드를 실행할 경우 세션이 초기화되므로 주의하세요
private func initializeSession(password: String) {
		let phrase = cryptographer.decrypt(password)
		if "Valid Password" == phrase {
				Session.initialze()
		}
}

6. TODO 주석

• TODO 주석은 프로그래머가 필요하다고 생각하지만 당장 구현하기 어려운 업무를 기술한다.
  • 더 이상 필요없는 기능을 삭제하라는 알림
  • 누군가에게 문제를 봐달라는 요청
  • 더 좋은 이름을 떠올려달라는 부탁
  • 앞으로 발생할 이벤트에 맞춰 코드를 고치라는 주의
• TODO로 떡칠한 코드는 바람직하지 않으므로 주기적으로 TODO 주석을 점검해 없애도 좋은 TODO는 정리한다.

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

나쁜 주석 (75p)

• 계속해서 강조하지만 함수나 변수로 충분히 표현할 수 있다면 주석을 달지 마라. ⭐️⭐️

1. 주절거리는 주석

2. 같은 이야기를 중복하는 주석 ⭐️

• 헤더에 달린 주석이 코드 내용을 그대로 중복하여 설명하는 주석이다. 이런 주석은 코드보다 더 많은 정보를 제공하지 못하는데도 개발자가 코드를 대충 이해하고 넘어가게 만든다.

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

• 2번과 비슷한 맥락의 주석이다. 주석에 담긴 살짝 잘못된 정보로 인해 개발자는 예상 못한 코드의 결과물을 맞닥뜨리게 됨.

4. 의무적으로 다는 주석

• 굳이 모든 함수나 변수에 주석을 달 필요가 없다.

5. 이력을 기록하는 주석

• 주석에다가 이제껏 모듈에 가한 변경을 모두 기록하는 일지로 사용하는 경우도 과거에는 있었다.
• 요즘은 소스 코드를 관리하는 깃허브가 있으니까 이런 행동은 이제 굳이 할 필요가 없음

6. 있으나 마나 한 주석

• 2번과 비슷한 맥락의 주석이다. 코드만 읽어도 알 수 있는 곳에다 굳이 주석을 달 필요는 없다.
• 있으나 마나 한 주석을 달지말고 코드를 깔끔하게 정리하자.

7. 위치를 표시하는 주석

• 어떤 소스 파일을 빠르게 찾기 위해 주석을 사용하는 경우도 있는데, 너무 자주 사용하지 않고 아주 드물게만 사용한다면 눈에 띄며 주의를 환기할 수 있음.

8. 닫는 괄호에 다는 주석 ⭐️⭐️

• 보통 중첩이 심하고 장황한 함수나 길이가 너무 긴 if~else 문에다가 이 주석을 달아놓는다.
• 닫는 괄호에 주석을 달아야겠다는 생각이 들면, 함수의 길이를 줄이려고 시도해보자.

9. 공로를 돌리거나 저자를 표시하는 주석

10. 주석으로 처리한 코드 ⭐️⭐️

• 다른 개발자들과 협업할 때 주석으로 처리된 코드는 다른 개발자들이 지우기를 주저한다. 이유가 있어서 남겨놓았거나 중요하니까 지우면 안 된다고 생각한다.
• 주석으로 처리한 코드는 그냥 지우라. 계속 남겨놓으면 쓸모 없는 코드가 점차 쌓여간다.

11. HTML 주석

12. 전역 정보를 담은 주석

• 주석을 꼭 달아야 한다면 근처에 있는 코드만 기술하자.
• 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하면 안 된다.

13. 너무 많은 정보

• 주석에다가 쓸데없는 정보는 쓰지 마라.

14. 주석 자체가 설명이 필요한 주석

15. 짧은 함수를 사용하라. 짧은 함수는 주석이 필요없다.

• 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석을 추가한 함수보다 훨씬 좋다.