TIL 3줄 요약
주석은 정말 필요한 경우에만 사용해야 하며, 대부분의 경우 좋은 네이밍과 함수 분리를 통해 코드 자체가 문서가 되도록 해야 한다.
이 주석이 정말 필요한가?를 자문하고, 주석 대신 더 명확한 함수명이나 변수명으로 개선할 수 있는지 고민해보자.
TIL 날짜
2025.07.09 ~ 2025.0.10
오늘 읽을 범위
- 주석
책에서 기억하고 싶은 내용
주석이 필요한 상황에 처하면 곰곰이 생각하기 바란다.
코드만이 정확한 정보를 제공하는 유일한 출처다. 그러므로 우리는 주석을 가능한 줄이도록 꾸준히 노력해야 한다.
- 좋은 주석
- 법적인 주석
- 정보를 제공하는 주석
- (결정에 깔린) 의도를 설명하는 주석
- 의미를 명료하게 밝히는 주석
- 결과를 경고하는 주석
- TODO
- 중요성을 강조하는 주석
- 공개 API에서 Javadocs
- 나쁜 주석
- 주절거리는 주석
- 같은 이야기를 중복하는 주석
- 오해할 여지가 있는 주석
- 의무적으로 다는 주석
- 이력을 기록하는 주석
- 있으나 마나 한 주석
- 무서운 잡음
- 위치를 표시하는 주석
- 닫는 괄호에 다는 주석
- 공로를 돌리거나 저자를 표시하는 주석
- 주석으로 처리한 코드
- HTML 주석
- 전역 정보
- 모호한 관계
- 함수 헤더
- 비공개 코드에서 Javadocs
오늘 읽은 소감
좋은 주석은 코드가 표현할 수 없는 맥락, 의도, 주의사항을 전달하고,
나쁜 주석은 코드를 읽으면 알 수 있는 당연한 내용을 반복하는 것이다.
나도 과거에 HTML 섹션을 구분지을때 시작과 종료를 표시하는 주석을 달았었고, CSS나 JS에는 설명과 저자를 표시하는 주석을 달았었다. 코드가 수정되면 주석도 바꿔줘야 하는데 시간이 흐른뒤 주석은 쳐다보지 않게 되었고 과거의 내용을 담고 있는 도움되지 않는 메모로 남겨진 기억이 있다. 지금은 영원한 숙제로 남아있는 TODO 주석과 부연 설명을 하는 주석을 사용중인데, IDE 기능이 워낙 좋아져서 솔직히 주석은 TODO 빼면 쓸 일이 없을 것 같다. 이름만으로도 설명이 가능하게 신경 써서 코드를 짜면 되는 단순한 이치, 제일 어려운 기본 지키기🥹
나의 최애 북틸
나와 생각이 비슷한 분들이라 동질감을 느꼈다. 자신의 상황에 빗대어 설명하는 부분과 정말 공부를 기록하는게 보여서 좋았다.
계속해서 보완중