Skip to content

주석.md

Latest commit

 

History

History
81 lines (61 loc) · 2.75 KB

주석.md

File metadata and controls

81 lines (61 loc) · 2.75 KB

Chapter 4. 주석

Table of Contents

"나쁜 코드에 주석을 달지 마라. 새로 짜라." - 브라이 언 W. 커니핸, P.J.폴라우거

  • 잘 달린 주석은 그 어떤 정보보다 유용하다.
  • 코드로 의도를 전부 표현할 수 없어 사용하는 것이 주석이다.
    • 코드로 의도를 표현할 방법은 없을까?
    • 모든 표현을 코드로 할 수 있도록 하자.
  • 주석의 유지보수가 쉽지 않아 코드를 따라가지 못하여 그릇될 가능성도 커진다.
    • 부정확한 주석은 아예 없는 주석보다 나쁘다.

좋은 주석

법적인 주석

  • 저작권 정보와 소유권 정보

정보를 제공하는 주석

  • 기본적인 정보를 주석으로 제공하면 편리하다.
    • 함수 이름에 정보를 담는 편이 더 좋다.
🙂 
// 테스트 중인 Responder 인스턴스를 반환한다.
protocol Responder {
    func responderInstance()
}

함수 이름에 정보를 담는다.
😀
protocol Responsder {
	func responderBeingTested()
}

의도를 설명하는 주석

  • 때때로 주석은 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명한다.

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

  • 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.
assertTrue(a.compareTo(a) == 0); // a == a

TODO 주석

  • 같앞으로 할 일'을 //TODO 주석으로 남겨둔다.
    • 단, 나쁜 코드를 남겨두는 핑계가 되면 안된다.

나쁜 주석

  • 주절거리는 주석
  • 같은 이야기를 반복하는 주석
    • 코드의 내용을 주석으로 반복하지마라
  • 오해할 여지가 있는 주석
  • 의무적으로 다는 주석
  • 이력을 기록하는 주석
    • 소스 코드 관리 시스템에 전부 나온다.
  • 공로를 들리거나 저자를 표시하는 주석
    • 소스 코드 관리 시스템에 전부 나온다.
  • 있으나마나한 주석
    • 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석
  • 함수나 변수로표현할 수있다면 주석을 달지마라
  • 주석으로 처리한 코드
    • 다른 이가 보았을 때, 지워도 될지 의문을 갖게 된다.
  • 함수 헤더
    • 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.