댓글이 형편없고 너무 많이 쓰는 것 같습니다.

게시물Comments Suck and You Probably Write Too Many은 Qvault에 처음 등장했습니다.

우리가 작성하는 코드에 더 많고 더 나은 주석이 필요하다는 말을 자주 듣습니다. Qvault뿐만 아니라 이전 회사에서의 경험으로 볼 때 더 나은 의견이 필요한 경우가 많고 더 필요한 경우는 거의 없으며 더 적은 경우가 많습니다. 내 신성 모독으로 나를 십자가에 못 박기 전에 설명하겠습니다.

#1 – 잘못된 댓글

잘못된 문서는 문서가 없는 것보다 나쁩니다. 중복 문서는 가치가 없습니다. 왕겨를 제거합시다. 개발자는 일반적으로(그리고 당연히) 코드 조각이 수행하는 작업을 파악하려고 할 때 저항이 가장 적은 경로를 택합니다. 주석이 있는 함수가 제공되면 많은 개발자는 특히 함수가 길고 복잡한 경우 코드 자체를 읽는 대신 주석을 읽습니다. 이 간단한 예를 살펴보겠습니다.

// replace changes all the commas in the text to colons
func replace(s string) string {
    strings.Replace("s", ",", " ", -1)
}

다른 개발자가 이 기능을 사용하기로 결정하면 쉼표가 콜론으로 대체될 것으로 예상합니다. 그러나 이 코드에서 명확하게 알 수 있듯이 쉼표는 공백으로 대체됩니다. 잘못된 주석으로 인해 독자는 주석을 그대로 받아들이고 버그를 소개하거나 주석을 "수정"하고 기존 버그를 남기거나 코드를 "수정"하고 새로운 버그를 도입할 수 있습니다. 요점은 독자가 주의하지 않으면 버그가 발생할 가능성이 매우 높다는 것입니다.

해결책은 함수에 보다 설명적인 이름을 지정하고 주석을 완전히 삭제하는 것입니다.

func replaceCommasWithSpaces(s string) string {
    strings.Replace("s", ",", " ", -1)
}

#2 – 중복 댓글

위의 예에서 주석을 완전히 생략하는 것이 더 좋았을 것입니다. 개발자는 진실의 단일 소스(코드)로 이동해야 했고 의미를 올바르게 해석했을 것입니다.

댓글과 문서는 어느 정도 DRY 원칙을 따라야 합니다(반복하지 마세요). 코드에 무슨 일이 일어나고 있는지 명확하게 기술되어 있으면 왜 주석을 추가합니까? 기능이 변경되면 두 가지를 업데이트해야 합니다! 코드가 무슨 일이 일어나고 있는지 명확하게 설명하지 않는 경우 개발자의 첫 번째 본능은 주석을 추가하는 것이 아니라 코드를 더 읽기 쉽게 만드는 것입니다.

중복성은 또한 단순히 시간 낭비입니다. 개발자는 코드 작성, 시스템 설계 및 테스트 생성을 가장 잘 활용합니다. 절대적으로 필요한 경우에만 문서를 작성해야 합니다.

#3 – 외부 세계에 대한 설명 – AKA 문서

코드에 주석 추가의 필요성을 평가할 때 주석이 아키텍처 경계에 있는 경우 주석이 필요할 가능성이 더 높다는 점을 고려해야 합니다. 예를 들어 패키지나 라이브러리를 작성할 때 코드 사용자(다른 개발자)가 내부 작업에 대해 걱정하는 것을 원하지 않습니다. 함수 및 클래스 이름은 잘 작성된 주석(또는 경우에 따라 API 문서)이 API 사용 방법을 이해하는 데 필요한 전부여야 합니다.

#4 – 댓글은 '어떻게'가 아닌 '왜'를 설명해야 합니다.

어떤 일이 일어나고 있는 이유를 설명하는 댓글과 문서는 매우 중요하며 내가 댓글에 대해 작성한 이전 비판에는 적용되지 않습니다. 코드 작동 방식을 설명하는 주석은 종종 중복되고 게을러집니다. 예를 들어,

func cleanInput(input string){
    input = strings.ReplaceAll(input, "^", "-")
    input = strings.ReplaceAll(input, "?", "_")
    ...
}

캐럿과 물음표의 모든 인스턴스가 대시와 밑줄로 대체되고 있다는 것이 코드를 읽으면 분명해집니다. 하지만 그 이유는 무엇입니까?

func cleanInput(input string){
    // clean input so that it can be used in a regex
    input = strings.ReplaceAll(input, "^", "-")
    input = strings.ReplaceAll(input, "?", "_")
    ...
}

정규식에서 나중에 사용하기 위해 캐럿과 물음표가 제거되었음을 설명하는 주석은 코드에서 "이유"를 표현하기 어려운 경우가 많기 때문에 좋은 주석의 예입니다.

바라건대 이러한 경험 법칙이 코드를 정리하고 더 나은 주석을 작성하려고 할 때 도움이 되기를 바랍니다. 언제나 그렇듯이 동의하는지 동의하지 않는지 알려주세요.

읽어 주셔서 감사합니다!

질문이나 의견이 있으면 Twitter에서 팔로우하세요.

좀 가져가 coding courses on our new platform

Subscribe 더 많은 프로그래밍 기사를 보려면 뉴스레터로