▲

GN⁺: Why Not Comments

 (buttondown.com)
3P by neo 8일전 | favorite | 댓글 1개
  • Why not "why not" comments? Not why "not comments"
    • “왜 ‘왜 안 됐는지’에 대한 주석을 남기지 않나요? ‘주석을 왜 달지 않았는지’에 대한 이유를 묻는 것이 아니에요.”

Why Not Comments

  • 코드는 구조화된 기계 언어로 작성되며, 주석은 표현력이 풍부한 인간 언어로 작성됨
  • "무엇"을 주석으로 달지 말고 가능한 한 많은 정보를 식별자에 포함시키라는 의미
  • 최근에는 "왜"도 주석에 포함시키지 말고 LongFunctionNames나 테스트 케이스 이름에 포함시키라는 주장도 있음
  • "자체 문서화" 코드베이스는 식별자를 통해 문서를 추가함

최근 예시

  • Logic for Programmers에서 나온 예시
  • epub 빌드가 수학 기호(\forall)를 기호(∀)로 변환하지 못하는 문제 발생
  • 수동으로 수학 문자열의 토큰을 유니코드로 대체하는 스크립트를 작성함
  • 16개의 수학 기호를 각각 대체하는 방식으로 작성했지만, 이는 비효율적임
  • 간단한 방법으로 주석을 달아 해결함
    • "각 문자열에 대해 16번 반복하지만, 현재 책에는 25개의 수학 문자열만 있고 대부분 5자 미만이므로 여전히 충분히 빠름"

왜 주석을 달아야 하는가

  • 느린 코드가 문제를 일으키지 않더라도 주석을 달아야 하는 이유
  • 미래에 코드가 문제가 될 수 있음
  • 주석은 트레이드오프를 인식하고 있음을 보여줌
  • 나중에 프로젝트를 다시 볼 때 왜 느린 코드를 작성했는지 이해할 수 있음

왜 자체 문서화가 불가능한가

  • "RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs" 같은 긴 함수 이름은 트레이드오프를 설명하지 않음
  • 함수와 변수 식별자는 하나의 정보만 포함할 수 있음
  • 주석을 테스트로 대체하는 것도 불가능함
  • 자체 문서화는 코드가 무엇을 하는지 설명하지만, 부정적인 정보는 코드가 무엇을 하지 않는지 설명함

뉴스레터 끝의 추측

  • "왜 안 되는지" 주석을 반사실적 사례로 생각할 수 있는지 궁금함
  • 인간 커뮤니케이션의 추상화는 자체 문서화가 불가능한가?
  • 비유, 불확실성, 윤리적 주장 등을 자체 문서화할 수 있는가?

GN⁺의 정리

  • 이 글은 코드 주석의 중요성과 그 한계를 다룸
  • 주석을 통해 코드의 트레이드오프를 명확히 하고, 미래의 유지보수를 용이하게 함
  • 자체 문서화의 한계와 주석의 필요성을 강조함
▲
neo 8일전  [-]
Hacker News 의견

  • 코드에 주석을 달 때, "왜"와 "왜 안 되는지"를 주로 설명함. 복잡한 코드일 경우 "무엇"을 간단히 설명하는 것도 유용함

    • 의무적인 주석은 비효율적이며, 모든 함수에 주석을 다는 것은 시간 낭비임
    • 도구가 자동으로 추가하는 주석도 비효율적임

  • 주니어 엔지니어는 코드가 무엇을 하는지 설명하는 주석을 작성하고, 중급 엔지니어는 왜 그렇게 작성했는지 설명하며, 시니어 엔지니어는 다른 방식으로 작성하지 않은 이유를 설명함

  • 유지보수자를 위한 주석 템플릿을 사용함

    • "이 코드는 <이유> 때문에 이렇게 작성됨. 수정하려고 시도한 후 실수임을 깨달으면, 다음 사람을 위해 카운터를 증가시켜 주세요: total_hours_wasted_here = n"

  • 코드에서 놀라운 부분에 주석을 다는 것이 중요함

    • 코드가 나중에 이해될지 확신이 서지 않을 때 "왜 안 되는지"를 설명하는 주석을 작성함

  • 주석의 중요성을 강조하며, 특히 자신의 코드를 5, 10, 15년 후에도 유지보수해야 할 때 유용함

    • 기존 코드와 일관성을 유지하는 것이 중요함

  • "순진한 해결책이 아닌 것"에 주석을 다는 것이 좋음

    • 비효율적인 코드가 나중에 수정될 때 문제를 일으킬 수 있음

  • 긴 함수 이름이나 테스트 케이스 이름에 주석을 포함시키는 것이 좋음

    • 메서드 이름이 명확하지 않을 때 주석이 도움이 됨
    • 메서드 설명에 "그리고"가 포함되면 메서드가 너무 많은 일을 하고 있다는 신호임

  • 디버그 로깅을 통해 입력이 원래 설계 제약보다 클 때 경고를 추가하는 것도 유용함

  • 주석과 문서 주석을 많이 사용하는 것을 선호함

    • 애플리케이션의 단계별로 주석을 작성하고, 코드를 작성하면서 주석을 세분화함
    • 모든 함수와 변수에 주석을 다는 것을 선호함

  • 코드 리뷰에서 예상되는 비판을 미리 방지하기 위해 "X를 하지 않은 이유는 Y 때문"이라는 주석을 작성함

답변달기