주석은 코드를 대신하지 못한다
주석은 도움이 될 때도 있지만, 코드의 부족함을 덮어주는 도구는 아니다. 실제로 실행되는 것은 코드이고, 주석은 시간이 지나면 코드와 어긋날 수 있다. 코드가 바뀌었는데 주석이 함께 바뀌지 않으면 설명은 오히려 잘못된 단서가 된다.
그래서 먼저 해야 할 일은 주석을 잘 쓰는 것이 아니라 주석이 덜 필요하도록 코드를 쓰는 것이다. 이름을 명확히 붙이고, 함수를 적절히 나누고, 조건문을 읽기 좋게 정리하면 많은 설명이 자연스럽게 사라진다.
표현력 있는 코드가 우선이다
복잡한 조건 위에 “사용 가능한 사용자인지 확인”이라고 주석을 붙이는 것보다, 조건을 isActiveUser() 같은 함수로 추출하는 편이 낫다. 주석은 읽는 사람에게 한 번 더 해석을 요구하지만, 잘 지은 이름은 코드의 일부로 계속 검증된다.
주석이 필요한 순간은 대체로 코드만으로 충분히 드러나지 않는 배경을 설명할 때다. 왜 이런 선택을 했는지, 외부 API의 이상한 제약 때문에 어떤 우회를 했는지, 법적 고지가 필요한지처럼 코드의 형태만으로 알기 어려운 맥락이 있다. 이런 주석은 코드를 보완한다.
도움이 되는 주석과 방해되는 주석
좋은 주석은 독자가 놓치기 쉬운 의도나 제약을 짧게 알려준다. 예를 들어 특정 알고리즘을 선택한 이유, 성능상 어쩔 수 없는 절충, 외부 시스템과 맞추기 위한 규칙은 코드만으로 완전히 설명하기 어렵다. 이런 경우 주석은 판단의 배경을 남겨 이후의 변경을 돕는다.
반대로 나쁜 주석은 코드를 그대로 반복하거나, 오래된 정보를 남기거나, 주석 처리된 코드를 방치한다. i++ 옆에 “i를 1 증가”라고 쓰는 주석은 아무것도 더하지 않는다. 더 이상 쓰지 않는 코드는 버전 관리 시스템이 보관하므로 파일 안에 남겨둘 이유가 거의 없다.
주석은 책임을 만든다
주석을 남기면 그 주석도 유지보수 대상이 된다. 코드만 고치고 주석을 잊으면 독자는 둘 중 무엇을 믿어야 할지 고민하게 된다. 그래서 주석은 적을수록 좋고, 남긴다면 오래 버틸 수 있을 만큼 정확해야 한다.
이 장의 핵심은 주석을 금지하자는 것이 아니다. 주석이 필요한 순간을 더 신중하게 고르고, 그 전에 코드 자체를 더 분명하게 만들자는 것이다. 설명보다 표현이 먼저다.
다음장으로 5장