.png)
TIL (Today I Learned)
2022.02.28
오늘 읽은 범위
4장 주석
😃 책에서 기억하고 싶은 내용을 써보세요.
부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다. 코드만이 정확한 정보를 제공하는 유일한 출처다. 그러므로 우리는 주석을 가능한 줄이도록 꾸준히 노력해야 한다.(p.69)
- 주석은 나쁜 코드를 보완하지 못한다.
- 코드로 의견만을 표현하라.
- 좋은 주석 (p.70 ~ p.75)
- 법적인 주석 (계약 조건 or 법적인 정보, 표준 라이선스 등)
- 정보를 제공하는 주석 (가능하다면, 함수 이름에 정보를 담아라)
- 의도를 설명하는 주석 (구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명하는)
- 의미를 명료하게 밝히는 주석 (모호한 인수나 반환값을 명확하게 도와주는)
- 결과를 경고하는 주석
- TODO 주석 (앞으로 할 일 , 삭제 or 요청, 부탁, 주의 등/ 주기적으로 점검해 없애주기)
- 공개 API에서 Javadocs
- 나쁜 주석 (p.75 ~ p.94)
- 주절거리는 주석 (이해가 안되어서 독자와 제대로 소통하지 못하는 주석은 안됨)
- 같은 이야기를 중복하는 주석
- 오해할 여지가 있는 주석 (살짝 잘못된 정보가 될 수 있는 주석)
- 의무적으로 다는 주석
- 이력을 기록하는 주석 (일지 혹은 로그같은 주석 - 혼란만 야기할 뿐이다)
- 있으나 마나 한 주석
- 무서운 잡음 (때로는 Javadocs도 잡음이다.)
- 함수나 변수로 표현할 수 있다면 주석을 달지마라. (좋은 주석에서도 나왔던 이야기, 주석이 필요하지 않도록 코드를 개선하자)
- 위치를 표시하는 주석 (ex. //////Action////// 너무 자주 사용하지 않는다면 눈에 띄며 주의를 환기 시키지만, 반드시 필요할 때만 드물게!! 흔한잡음이 된다.)
- 닫는 괄호에 다는 주석 (작고 캡슐화된 함수에는 잡음이다.)
- 공로를 돌리거나 저자를 표시하는 주석 (이런 정보는 소스코드관리시스템에)
- HTML 주석 (혐오 그 자체이다 ex. / </ pre> /)
- 전역 정보 (주석을 달아야한다면 근처에 있는 코드만 기술)
- 너무 많은 정보
- 모호한 관계 (독자가 읽고 무슨 소리인지 알아야한다.)
- 함수 헤더 (짧은 함수는 긴 설명이 필요없다. 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.)
- 비공개 코드에서 Javadocs
🤔 오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요
저자는 이번 장의 반절을 나쁜 주석에 대해 설명한다. 역시 하라는 것보다 하지 말라는게 더 재밌고 번번히 일어나는 법 !! 코드만큼이나 자주 작성하는게 주석인데 주의 또 주의해야겠다.
