클린코드(Clean code) 4장 - 주석

1. 주석을 최대한 쓰지 말자

개판 치고 주석으로 해명하는 것보다는 의미 있는 네이밍과 코드가 중요하다.

코드는 변화하는데, 주석이 쫓아가지 못하면 의미없는 컴파일도 안되는 텍스트 나부랭이

 

..???????이게 가능한가 근데?

한번 쓰고 버릴 코드도 아니고 N년동안 기우고 굴려야 하는 sm입장에서는 히스토리 남기는 것도 너무 필요한 일인데...

인수인계할 때도 그렇지만, 과거의 나를 현재와 미래의 내가 믿지 못하는 사태가 너무 많음.

소스 커밋 체크인할 때 버전별 비교가 가능하지만 그거 가지고는 완전하지 않음

 

나는 그래서 날짜별로 상세하게

20220801 ~~ 기능 추가 / 요청자 ㅇㅇ부서 김뫄뫄 책임 이런식으로

어떻게든 기억날 수 있게 히스토리를 남기는 편.

AA하면 BB하게 같은 기능 설명도 같이 하는 편이지만... 너무 거기에 집착할 필요는 없을 듯.

근데 야근하면서 술 마시고 코딩한 티가 나는 주석이라든가(네 과장님 얘기 맞아요)... 그런건 좀 그렇긴 함.

너무 뻔한 주석도 굳이 싶고.

 

2. 좋은 주석의 특징

1) 구현에 대한 정보 제공

2) 의도와 중요성 설명

그러니 이에 해당하지 않는 주석은 굳이 가급적 남기지 않는 걸로

 

3. TODO / FIXME

TODO : 앞으로 해야할 일. 나는 가끔 TBD(TO BE DECIDED)로 쓰고 나중에 추가하기도

FIXME : 당장은 수정할 필요 없지만 언젠가 고치긴 해야할 때 , 가능한 빨리 수정해야

사실 보완 필요하다고 달아놓고 못 고치고 있는거 많기는 함.... ㅇㅈ

인텔리제이에서는 하이라이팅 빡 되고, 하단 TODO 탭에서도 따로 모아 볼 수도 있어서 좋더라.

회사 에디터는 인텔리제이가 아니지만, 나도 TODO / FIXME는 써봐야겠다

 

4. Annotation

코드에 대한 메타데이터. java.lang.annotation

코드 실행흐름에 간섭을 주거나, 주석처럼 정보를 주기도 함.

@Deprecated, @Override 같은 건 많이 본 듯.

스프링에서도 많이 사용함

근데 이건 자동 생성되는 경우가 많던데 .. 여튼 코드 한복판에 취소선 가는거는 꼴뵈기 싫으니 지양하는걸로

라벨달듯 잘 사용하면 그것도 좋은거 같음

 

5. Javadoc

java코드 api문서에서 HTML 형식으로 주석을 볼 수 있게 만드는 도구

공개될 일이 있다면 javadoc를 잘 작성하는 것이 중요

나는 소스를 웹에서 띄워 볼 일이 없긴 한데 프레임워크가 맨 처음 메인 클래스 단 주석을 이렇게 생성하던데