오늘 읽은 범위
4장 주석
책에서 기억하고 싶은 내용을 써보세요.
코드만이 정확한 정보를 제공하는 유일한 출처다. 그러므로 우리는 주석을 가능한 줄이도록 꾸준히 노력해야 한다.
좋은 주석
- 법적인 이유로 다는 주석
- 의도를 설명하는 주석
- 결과를 경고하는 주석
- 모호한 인수나 반환값의 의미를 밝히는 주석
- 앞으로 할 일을 남기는 TODO 주석
- 중요성을 강조하는 주석
나쁜 주석
- 별다른 이유 없이 달린 주석
- 코드를 그대로 풀어놓은 주석
- 오해의 여지가 있는 주석
- 변경 이력을 모두 기록하는 주석(일종의 로그)
- 정보를 제공하지 못하는 주석
- 함수나 변수로 표현할 수 있는 주석
- 위치를 표시하는 주석
- 누가 무엇을 추가했는지 표시하는 주석
- 코드를 주석으로 처리한 경우
- 시스템의 전반적인 정보를 기술한 주석
- 모호한 관계의 주석
오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요.
- 주석을 최소화하기를 권장하기에 좋은 주석보다는 나쁜 주석의 사례가 많았다.
- 업무에서 TODO 주석을 사용하고 있긴 한데 관리를 안하면 있으나마나 하기 때문에 진짜 좋은 주석인지는 모르겠다. 실제로 수정하고나서 주석을 삭제안해서 계속 남아있는 경우도 많았다.
- 난 주로 위치를 표시하는 주석을 자주 쓴다. 컴포넌트나 함수가 잘게 잘 쪼개져있으면 쓸 일이 없겠지만 실무에서는 그렇게 클린하게 짜인 코드를 보기가 힘들다. 코드가 길어지고 비슷한 코드가 반복되면 주석으로 위치를 찾는게 도움이 많이 된다. 물론 리팩토링해서 코드를 잘게 쪼개는게 가장 좋겠지만 현실은… 😢
궁금한 내용이 있거나, 잘 이해되지 않는 내용이 있다면 적어보세요.
javadoc?
- 클래스, 메서드, 필드 등에 대해 자동으로 문서화를 생성할 수 있도록 도와주는 특수한 주석 문법
최애 북틸
- 본인이 잘못하고 있던 점에 대해서 솔직하게 소감을 남긴 부분이 인상깊다.
- 각 파트마다 한 문장 요약한 것이 눈에 띈다. 궁금한 점도 코드까지 작성하며 공부하신 흔적이 보여서 좋다.
- 직접 코드 예시를 들어 간결하게 요약하신 것이 짧고 임팩트 있었다. ‘영어권이 아닌 국가에서는 영어로 길게 쓰인 함수명보다는 해당 언어로 쓰인 주석이 낫지 않을까’라고 의문을 제기하신 부분도 타당한 주장이라고 생각한다.