불필요한 주석과 불필요해진 주석

가치가 낮은 주석을 크게 두 가지로 나눌 수 있다고 생각 했습니다.

1. 불필요한 주석
   • 코드만으로 충분히 이해할 수 있는 내용을 중복 설명하는 주석
2. 불필요해진 주석
   • 복사, 붙여 넣기 또는 코드 변경으로 인해 더 이상 유효하지 않게 된 주석
   • 오해의 소지가 있어 코드 이해를 방해
     주석이 애플리케이션 코드 동작에 직접적인 영향을 주지 않지만, 가독성과 유지보수에 큰 영향을 미칠 수 있기 때문에 엄격하게 관리 될 필요가 있다고 생각 했습니다.

도메인에 대한 이해

주석의 가치를 올바르게 판단하기 위해서는 서비스 도메인에 대한 깊은 이해가 선행되어야 합니다. 이것은 단순히 기술적인 관점에서 코드를 이해하는 것을 넘어, 그 코드가 왜 필요한지 안다는 것을 의미합니다.

서비스 도메인에 대해 깊이 이해하면 다음과 같은 이점이 있습니다.

1. ‘왜 해야 하는지’, ‘무엇을 하려고 하는지’ 알기 때문에 서비스의 가치를 지킬 수 있다.
2. 해결하고 싶은 것이 무엇인지 알기 때문에 문제에 집중할 수 있다.
3. 기존의 해결 방법에 얽매이지 않고, 새로운 해결 방법을 도출할 수 있다.
4. 타 부서 사람들(ex, 기획자)과 의사소통 과정에 오해를 줄일 수 있다.

코드의 표현력이 충분하다면 주석은 지우자

설계의 최신 내용은 코드이고 가장 현행화된 설명이 코드라고 생각합니다.

앞서 14장에서 설명하는 주석이 효용성이 있었던 이유는 코드의 표현력의 한계로 인해 추가적으로 이해하하는 시간이 필요할 때 시간을 절약하는 차원이었습니다.

따라서 코드 표현력에 충분하다면 주석은 지우는 것이 복잡도를 줄이는 방법이라고 생각합니다.

바로 직전에 적은 내용이 나와서 당황했습니다.

이번장은 읽으니 이런 생각이 듭니다.
코드정리하는 대신에 주석을 작성하는 것으로 편익을 누렸으면 그것을 유지보수하는 책임도 따른다.
(주석은 지속적인 관리대상이 되니까요)
그러므로 시간을 들여서 코드정리를 할 지, 시간을 좀 덜 들이고 주석을 작성하고 유지보수할지, 테스트코드를 만들지 평가하여 선택하면 되겠다는 생각이 듭니다.

굉장히 어렵게 만들어져 정리하기도 어렵고 변경&확장할 여지가 없는 코드라면 주석이 가치있을 것 같고,
어렵게 만들어져있으나 계속 변경&확장의 여지가 있는 코드라면 시간을 들여 코드정리를 하는 것을 택하는 등, 상황에 맞게 선택하면 될 것 같다는 생각이 듭니다.

소통 의무에 대해 편협한 시각

가끔은 소통 의무에 대해 편협한 시각을 가진 이들이 모든 루틴에 주석을 달아야 한다는 식의 독단적인 규칙을 고집하기도 합니다.

14장 제 댓글에서 모든 메소드에 JavaDoc 을 달았던 일을 떠올립니다. 쓰다 보면 영어로 된 메소드명을 한국어로 옮기고 있다는 생각도 들더군요. 결국 같은 내용을 반복하고 있었던 것입니다.(물론 작문에 서툴렀던 것도 있었던 것 같습니다)

주석은 사람을 겨냥한 것

코멘트는 컴퓨터를 겨냥하는 것이 아니라 프로그램을 읽는 사람을 겨냥 합니다. <코드 크래프트>

<코드 크래프트>에서 언급 되었듯이 주석은 컴파일러에게 아무런 의미가 없습니다.
하지만 코드를 읽는 사람은 주석에서 의미를 찾으려 하는 경향이 있습니다.
그래서 아래 처럼 종종 문제를 햇갈리게 합니다.

주석과 코드는 작성할 때와 나중에 볼 때, 시간이 흐르고 나면 서로 맞지 않는 경우가 있습니다.

주석 주도 개발?

다시 처음 문장으로 돌아가 봅니다.

코드만으로 내용을 이해할 수 있다면 주석은 삭제하세요.

저는 작성해야 할 로직이 복잡해서 햇갈릴 때면
처음에는 주석으로 대강의 로직을 한국어로 작성합니다.
숫자를 들여 쓰기하면서요.
1.
1.1
1.2
2.
2.1

그리고 코드를 작성하고 함수로 추출하고 최종적으로는 주석을 삭제합니다.

많은 분들이 이미 좋은 이야기들을 해주셔서 특별히 더 생각나는게 있지는 않지만
14, 15를 보면서 주석을 너무 부정적으로만 봤나 싶기도 했습니다.

캔트백도 비즈니스를 설명하는 주석을 쓰긴 쓰는구나
클린코드에서는 굉장히 부정적으로 표현한 것 같았는데, 캔트백의 표현은 좀 더 용납할만한 무언가구나 하는 생각이 들었습니다.