클린코드 중 주석에 대한 부분을 그대로 옮겨적는다.
글을 잘 정리하여 간결하게 적으려고 했는데, 무엇하나 버릴 내용이 없어서 그대로 옮겨 적는다.
잘 달린 주석은 그 어떤 정보보다 유용하다. 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다.
오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다.
주석은 쉰들러 리스트가 아니다. 주석은 '순수하게 선하지'못하다.
사실상 주석은 기껏해야 필요악이다. 프로그래밍 언어자체가 표현력이 풍부하다면, 아니 우리에게 프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면,
주석은 거의 필요하지 않으리라. 아니, 전혀 필요하지 않으리라.
우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다. 여기서 내가 실패라는 단어를 썼다는 사실에 주목한다. 진심이다. 주석은 언제나 실패를 의미한다.
때때로 주석 없이는 자신을 표현할 방법을 찾지 못해 할 수 없이 주석을 사용한다. 그래서 주석은 반겨 맞을 손님이 아니다.
그러므로 주석이 필요한 상황에 처하면 곰곰이 생각하기 바란다. 상황을 역전해 코드로 의도를 표현할 방법은 없을까? 코드로 의도를 표현할 때마다 스스로를 칭찬해준다. 주석을 달 때마다 자신에게 표현력이 없다는 사실을 푸념해야 마땅하다.
내가 이렇듯 주석을 무시하는 이유가 무엇이냐고? 거짓말을 하니까. 항상도 아니고 고의도 아니지만 너무 자주 거짓말을 하니까.
주석은 오래될수록 코드에서 멀어진다. 오래될수록 완전히 그릇될 가능성도 커진다. 이유는 단순하다. 프로그래머들이 주석을 유지하고 보수하기란 현실적으로 불가능하니까.
코드는 변화하고 진화한다.
일부가 여기서 저기로 옮겨지기도 한다. 조각이 나뉘고 갈라지고 합쳐지면서 괴물로 변한다. 불항하게도 주석이 언제나 코드를 따라가지는 않는다. 아니, 따라가지 못한다. 주석이 코드에서 분리되어 점점 더 부정확한 고아로 변하는 사례가 너무도 흔하다.
프로그래머들이 주석을 엄격하게 관리해야 한다고, 그래서 복구성과 관련성과 정확성이 언제나 높아야 한다고 주장할지도 모르겠다. 그 의견에 동의한다. 프로그래머들에게도 절도가 필요하다. 하지만 나라면 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로, 그래서 애초에 주석이 필요 없는 방향으로 에너지를 쏟겠다.
부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다. 부정확한 주석은 독자를 현혹하고 오도한다. 부정확한 주석은 결코 이뤄지지 않을 기대를 심어준다.
더 이상 지킬 필요가 없는 규칙이나 지켜서는 안되는 규칙을 명시한다.
진실은 한곳에만 존재한다. 바로 코드다. 코드만이 자기가 하는 일을 진실되게 말한다. 코드만이 정확한 정보를 제공하는 유일한 출처다.
그러므로 우리는 (간혹 필요할지라도)주석을 가능한 줄이도록 꾸준히 노력해야 한다.
코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다. 모듈을 짜고 보니 짜임새가 엉망이고 알아먹기 어렵다. 지저분한 모듈이라는 사실을 자각한다. 그래서 자신에게 이렇게 말한다. "이런! 주석을 달아야겠다!"
아니다! 코드를 정리해야 한다!
표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다. 자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는 데 시간을 보내라!
정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이다.
좋은 주석
1. 법적인 주석
2. 결과를 경고하는 주석
3. TODO주석
4. 공개 API에서 Javadocs
나쁜 주석
대사수 주석이 이 범주에 속한다. 일반적으로 대다수 주석은 허술한 코드를 지탱하거나, 엉성한 코드를 변명하거나, 미숙한 결정을 합리화하는 등
프로그래머가 주절거리는 독백에서 크게 벗어나지 못한다.
1. 같은 이야기를 중복하는 주석
2. 오해할 여지가 있는 주석
3. 의무적으로 다는 주석
4. 이력을 기록하는 주석
5. 있으나 마나 한 주석