Five Lines of Code - 8. 주석 자제하기

주제: 주석의 위험성을 이해하고, 다양한 유형의 주석을 구별하며 처리하기

🔖 8.4 메서드의 이름으로 주석 대신하기

책의 내용

사람들은 긴 메서드명을 좋아하지 않는 경향이 있습니다. 그러나 자주 호출되는 메서드에 한해 그렇습니다. 언어에는 가장 많이 사용하는 단어가 가장 짧은 경향을 가지는 성질이 있습니다. 코드베이스도 마찬가지 입니다. 항상 사용하는 것에 대해서는 설명이 덜 필요하기 때문에 이것은 어쩌면 당연한 것입니다.

나의 생각

위의 문장에 정말 공감했다. 예를 들어 JavaScript에서의 배열 길이를 확인하는 메서드는 checkArrayHowLong가 아니라 .length라서 직관적이고 타이핑하기도 좋다.

그리고 그동안의 내 코드를 돌아보았다. 자주 호출하는 메서드에 필요 이상의 설명이 포함된 건 아니었는지 말이다. 의사소통을 알아듣기 쉽게 하려면 간결하면서도 직관적인 단어 사용에 고민을 많이 하면 좋다. 그러므로 앞으로는 사용 빈도가 높은 메서드는 더 간결하고 접근하기 쉬운 형태로 유지해야겠다.

🔖 8.5 불변속성을 문서화한 주석 유지

책의 내용

마지막 유형의 주석은 로컬이 아닌 불변속성을 문서화한 주석입니다. 여러 번 이야기한 것처럼 버그가 발생할 확률이 높은 곳입니다. 이를 판단하는 방법은 '이 주석으로 누군가 버그를 만드는 것을 막을 수 있는가?' 라고 자문해 보는 것입니다. 아래의 코드는 의심스러운 session.logout과 그 코드의 이유를 설명하는 주석을 볼 수 있습니다. 인증(또는 그와 같은 복잡한 상호작용)은 테스트하거나 시뮬레이션하기가 매우 어려울 수 있어 주석은 매우 당연한 것입니다.

// 다음 요청 때 강제로 재인증하도록 하는 로그아웃
session.logout();

나의 생각

위 주석은 이 로그아웃 함수 호출이 단순히 사용자를 로그아웃시키는 것 뿐만 아니라, 다음 요청 때 사용자가 '강제로 재인증을 받도록 만든다'는 추가적인 정보를 제공한다. 이는 특히 보안과 관련된 로직에서 중요할 수 있겠다. 만약 이 주석이 없다면 다른 개발자가 로그아웃 함수의 호출을 단순히 세션 종료로만 이해할 수 있고, 재인증 강제라는 중요한 부분을 간과할 수 있을 것 같다.

또한, 위와 같은 주석은 코드가 의도한 대로 작동하는지 테스트하는 데도 도움을 줄 것 같다. 복잡한 상호작용이나 보안 관련 기능은 테스트하기 어려울 수 있으니, 주석은 해당 기능의 동작을 정확히 이해하고 테스트 케이스를 작성하는 데 필요한 정보를 제공할 것 같다.