주석

좋고 나쁜 주석의 내용에 대해 알아보자.
간결한 정리를 위하여 코드를 ~~~로 생략하고 주석을 // 주석내용 통일한다.

프로그래밍 언어 자체의 표현력이 풍부하다면 주석은 필요없다

• 주석을 어떻게 쓸지 고민할 시간에 코드의 표현력에 신경써라
• 지저분한 로직에 주석을 달기보단, 명확한 함수명으로 분리하라.

(그나마) 좋은 주석

• 법적인 주석

// copyright (c) ~~ 
// 어떠어떠한 조건으로 배포한다.

• 정보를 제공하는 주석

// 테스트중인 responder 인스턴스를 반환한다
~~~~~~~

하지만 responderBeingTested라는 함수명으로 대체가능함.

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

~~~ // a === a
~~~ // a != b
~~~ // a < b

잘못된 주석을 달 확률이 높다. 따라서 양날의 검과 같고, 주석을 정확히 달도록 신경써야함.

• 결과를 경고하는 주석

// 여유 시간이 없다면 실행하지마세요
~~~

• Todo주석
• 중요성 강조 주석
• 너무 전문적인 지식에 관한 코드(ex.루프 한계값으로 제곱근을 사용한 이유)

// 배열에 있는 모든 배수는 배열 크기의 제곱근보다 작은 소수의 인수이다.
// 따라서 이 제곱근보다 더 큰 숫자의 배수는 제거할 필요가 없다.

나쁜 주석

• 주절거리는 주석

~~~
// 이건 어떠어떠한 의미다

특별한 이유없이 의무감으로 달은 주석 -> 시간낭비다

• 같은 이야기를 중복하는 주석
• 오해 할 여지가 있는 주석
• 의무적으로 다는 주석
• 이력을 기록하는 주석

2022-01-01 : 연혁 작성
2022-01-11 : 연혁에 창립일 추가
2022-01-16 : 연혁에 기념일 추가 ...

• 있으나 마나한 주석
  지나친 참견, 주석을 무시하는 습관에 빠짐
• 무서운 잡음
• 함수나 변수로 표현할수있다면 주석을 달지마라
• 위치를 표시하는 주석

// 여기서부터 드래그 로직!!
~~~drag~~~
// 여기까지가 드래그 로직 !!

// 여기서부터 드롭 로직!!
~~~drop~~~
// 여기까지 드롭 로직!!

• 닫는 괄호에 다는 주석

try{

} // 어떤것을 try한다
catch {

} // 어떤것에서 오류가 발생시

중첩이 심하고 장황하면 ㅇㅈ 아니면 걍 함수를 줄이셈

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

// 이건 Nick이 짠 코드입니다

• 주석으로 처리한 코드
  주석으로 처리된 코드는 무언가 의미가 있는거같아 사람들이 지우기 꺼려한다. -> 더 위험함
• HTML 주석
  미친놈ㅇㅇ
• 전역 정보

// 적합성 테스트가 동작하는 포터 : 기본값은 8080
~~~
~~~

주석을 달아야 한다면 근처에 있는 코드만 기술해라. 시스템의 전반적인 정보를 코드 일부에 기술하지마라.

• 너무 많은 정보
• 모호한 관계

// 모든 픽셀을 담을 배열로 시작한다. (여기서 필터바이트를 더한다)
// 그리고 헤더 정보를 위해 200 바이트를 더한다

필터바이트가 뭐임? 200바이트를 더하는이유는? -> 주석 자체가 의문을 만듦

• 함수 헤더
  긴설명 필요없고 짧고 한가지 수행명만 붙인 함수가 훨씬 좋다