주석은 동작 반복이 아니라 판단 근거를 남긴다

좋은 주석은 코드가 이미 말하는 “무엇”이 아니라, 코드만으로 안 보이는 “왜”와 “주의 조건”을 설명합니다.

질문

남길 주석

지울 주석

왜?

성능 우회, 임시 제약, 외부 API 제한처럼 선택 배경을 남긴다.

코드 한 줄을 한국어로 반복한다.

언제?

특정 입력, 플랫폼, 버전에서 조심해야 하는 조건을 적는다.

항상 맞을 것처럼 오래된 상황을 남긴다.

유지?

코드 변경 때 같이 확인해야 할 계약을 남긴다.

코드와 쉽게 어긋나는 구현 설명을 길게 둔다.

판단 기준: 주석을 지워도 코드의 이유가 사라진다면 남기고, 동작 설명만 반복한다면 코드로 표현합니다.