본문 바로가기
프로그래밍 놀이터/디자인 패턴, 리펙토링

[Clean Code] 주석.

by 돼지왕 왕돼지 2012. 2. 28.
반응형


♧ 주석은 나쁜 코드를 보완하지 못한다.



♧  주석 대신 코드로 의도를 표현하라.


♧ 좋은 주석은 매우 한정적이다.
  - 법적인 주석 ( Copyright 등 기술 )
  - 정보를 제공하는 주석 ( kk:mm:ss 형식 )
  - 의도를 설명하는 주석 ( 한번에 이해하기 어려운 알고리즘 등을 설명 )
  - 의미를 명료하게 밝히는 주석 ( API 자체가 잘못설계되어 이해가 어려울 때 이를 보충해주는 주석 )
  - 결과를 경고하는 주석 ( API 형태로. 사용자에게 경고를 함. i.e) 오래 걸리는 작업처리. not-thread-safe )
  - TODO 주석
  - 중요성을 강조하는 주석 ( 직관적으로는 중요하지 않아서 삭제되거나 편집될 수 있는 부분을 경고 )
  - 공개 API 의 Javadoc 형태


♧ 나쁜 주석
  - 별 의미 없이 주절거리는 주석
  - 코드로 대체 가능한 주석
  - 코드와 같은 이야기를 하는 주석
  - 유지보수 되기 힘든 주석 ( 주석도 유지보수가 필요하다!! -> So 가능하면 코드로 )
  - 오해 여지가 있는 주석 ( 의미가 clear 하지 않음. )
  - 의무적으로 다는 주석 ( 직관적으로 알 수 있으나 의미감으로 다는 주석 )
  - 이력을 기록하는 주석
  - 이전 코드를 backup 하는 형태의 주석
  - 의미없는 주석 ( 있으나 마나한 주석, API 에서도 마찬가지 )
  - 위치를 표시하는 주석 ( 어느 지점을 쉽게 표기하기 위해서 사용하는 주석 )
  - 닫는 괄호에 다는 주석 ( 함수를 줄이는 것이 좋다. )
  - 가변성이 큰 주석. ( 내용이 쉽게 false 될 수 있는 내용을 담고 있는 주석 )
  - 너무 많은 정보를 담고 있는 주석. ( 몰라도 되는 내용까지 세부적으로 설명 )
  - 비공개 코드의 Javadoc 


반응형

'프로그래밍 놀이터 > 디자인 패턴, 리펙토링' 카테고리의 다른 글

[Clean Code] 클래스  (0) 2012.02.28
[Clean Code] 형식  (0) 2012.02.28
[Clean Code] 함수  (0) 2012.02.28
[Clean Code] 의미 있는 이름.  (0) 2012.02.28
[Clean Code] 클린 코드란 무엇인가?  (0) 2012.02.28

댓글