Comment
주석은 코드가 말하지 못하는 의도와 제약을 남길 때 가치가 있다
컴파일러는 주석을 무시하지만, 사람은 주석으로 선택 이유와 안전성 전제를 읽는다. 구현 반복 설명은 빠르게 낡는다.
why
왜 이 구현을 골랐는지 기록한다.
risk
경계값, 안전성 전제, 성능 타협을 남긴다.
sync
코드가 바뀌면 주석도 함께 갱신한다.
읽기
코드만으로 충분한가
변수명과 함수명이 의도를 이미 말하면 주석은 줄인다.
판단
숨은 전제가 있는가
도메인 규칙, 성능 이유, unsafe 전제는 짧게 기록한다.
작성
현재가 아니라 이유를 설명
코드가 무엇을 하는지보다 왜 이렇게 하는지를 남긴다.
리뷰
코드와 주석 동기화
동작이 바뀌었는데 주석이 예전 설명이면 삭제보다 위험하다.
주석 유형
좋은 예
나쁜 신호
한 줄 주석
바로 아래 코드의 선택 이유를 짧게 보강한다.
코드와 똑같은 말을 자연어로 반복한다.
옆 주석
짧은 상수 의미처럼 시선을 끊지 않는 정보에 쓴다.
긴 설명이 줄 끝에서 잘려 읽기 흐름을 망친다.
문서화 주석
공개 API의 계약, 실패 조건, 예제를 남긴다.
구현 변경 후 공개 문서가 옛 동작을 설명한다.
반복 설명 금지
코드를 그대로 번역하는 주석은 코드 개선 신호일 수 있다.
제약 기록
입력 범위, 안전성 가정, 외부 시스템 이유는 남길 가치가 크다.
항상 동기화
틀린 주석은 없는 주석보다 유지보수 위험이 크다.