Programming/Clean Code

4장. 주석

JKROH 2023. 11. 10. 17:40
반응형
  • 분명 잘 달린 주석은 유용하다. 그러나 대부분의 주석이 그렇지 못하다.
  • 주석은 오래될 수록 코드에서 멀어진다. 주석을 유지하고 보수한다는 것은 현실적으로 어렵다.
  • 코드는 계속해서 변화한다. 때로는 위치가 달라지기도 한다. 주석도 그럴까? 쉽지 않다.
  • 부정확한 주석은 독자를 현혹하고 오도한다. 잘못된 결과로 독자를 이끌기도 하며 지킬 필요가 없거나 지키면 안되는 규칙을 명시한다.
  • 따라서 우리는 주석을 가능한 줄이도록 노력해야한다.

주석은 나쁜 코드를 보완하지 못한다

  • 일반적으로 주석을 다는 이유는 코드 품질이 나쁘기 때문이다.
  • 그러나 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가 복잡하고 어수선하며 주석이 많은 코드보다 낫다.

코드로 의도를 표현하라!

  • 아래 예시를 살펴보자. 만일 사용자가 게시글의 작성한 사람이 아니면 예외를 던진다.
        // 입력된 사용자 id와 게시글을 작성한 사용자 id가 다르다면 수정할 수 없다.
        if(user.getId()!=board.getUser().getId()){
            throw new RuntimeException("수정 권한이 없습니다.");
        }
  • 대신 조건절 자체를 하나의 함수로 표현하는 것이 낫다.
        if(!user.isAuthor(board)){
            throw new RuntimeException("수정 권한이 없습니다.");
        }

좋은 주석

  • 물론 좋은 주석도 존재한다. 아래 예시들이 그러하다.

- 법적인 주석

  • 법적인 정보를 담은 주석은 타당하다.
  • 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 소유권 정보는 필요하다.

- 정보를 제공하는 주석

  • 때로는 기본적인 정보를 주석으로 제공하면 편리하다.
  • 물론 주어지는 정보를 함수나 인수의 이름으로 적절히 표현하는 것이 더 낫다.

- 의도를 설명하는 주석

  • 때로는 주석이 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명한다.
  • 예를 들어, 객체 간 우선 순위를 결정해야 하는 경우에 주석을 통해 왜 우선 순위가 높은지를 설명할 수 있다.

- 의미를 명료하게 밝히는 주석

  • 인수나 반환값이 표준 라이브러리나 변경하지 모하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.
  • 그러나 이런 주석을 달 때는 그릇된 의미의 주석을 달 가능성도 항상 내포되어있음을 명심하라.

- 결과를 경고하는 주석

  • 예를 들어 수행 시간이 매우 긴 테스트 코드에는 가급적 수행하지 말라는 경고를 남길 수 있다.

- TODO 주석

  • 향후 처리해야할 일들은 TODO주석으로 남겨두면 좋다.
  • 그러나 TODO를 너무 남발하지는 말자. 주기적인 확인을 통해 완료된 TODO는 삭제하는 것이 좋다.

- 중요성을 강조하는 주석

  • 별 것 아니라고 느껴질 수 있는 무언가의 중요성을 주석을 통해 강조할 수 있다.

- 공개 API에서 Javadocs

  • 공개 API를 작성한다면 Javadocs 역시 잘 작성해야한다.
  • Javadocs 역시 주석임을 명심하라. 정확하고 올바른 정보만을 전달해야한다.

나쁜 주석

  • 대부분의 주석은 나쁘게 작용할 여지가 많다. 아래 예시를 통해 알아보자.

- 주절거리는 주석

  • 주석을 작성해야 한다면 충분한 시간을 들여 최고의 주석을 달도록 노력해라.
  • 주석을 다는 목적과 이유를 명확히 하고 이를 바탕으로 반드시 필요한 정보만을 주석에 담아라.

- 같은 이야기를 중복하는 주석

  • 코드 내용을 그대로 설명하기만 하는 주석은 어떤 의미도 없다.

- 오해할 여지가 있는 주석

  • 정확하지 않은 정보를 담은 주석은 독자가 오해할 수 있게 만든다.

- 의무적으로 다는 주석

  • 의무적으로 주석을 달지 말아라.
  • 예를 들어, 모든 함수에 Javadocs를 다는 것은 무의미하다.

- 이력을 기록하는 주석

  • 소스 파일에 변경, 수정 등의 이록을 기록하지 마라.

- 있으나 마나 한 주석

  • 있으나 마나 한 주석이 많아지면, 독자가 다른 주석도 무시하게끔 만들 수 있다.
  • 반드시 필요한 주석만을 달도록 하자.

- 무서운 잡음

  • 의무적으로 생각없이 작성한 Javadocs에 잘못된 정보가 담긴다면, 이를 읽는 사람은 큰 오해를 할 수도 있다.

- 함수나 변수로 표현할 수 있다면 주석을 달지 마라

  • 일단은 코드로 먼저 표현하고, 정말 필요하다면 주석을 달지 결정해야한다.

- 위치를 표시하는 주석

  • 배너 주석을 통해 특정 정보들의 위치를 표시할 수도 있지만, 남발하지 말아라.

- 닫는 괄호에 다는 주석

  • while 이나 if, try-catch 등의 닫는 괄호에 다는 주석은 중첩이 심하다는 것을 보여줄 뿐이다.
  • 주석을 달 것이 아니라 함수를 분리하거나 줄여야 한다.

- 공로를 돌리거나 저자를 표시하는 주석

  • 누가 어떤 코드를 작성했는지는 커밋하면서 다 남길 수 있다.

- 주석으로 처리한 코드

  • 주석 처리한 코드는 독자가 해당 코드가 필요한지 아닌지를 헷갈리게 만든다.
  • 불필요하다면 지워라, 다시 필요해진다면 롤백해라.

- HTML 주석

  • 주석에 HTML 태그를 사용하지 말아라. 보기 너무 불편하다.

- 전역 정보

  • 주석은 해당 주석이 달린 부분에 국한되어서만 적용되어야 한다. 시스템의 전반적인 정보를 주석에 기술하지 마라.

- 너무 많은 정보

  • 주석에 너무 많은 정보를 담는 것은, 코드를 깔끔하지 않게 작성했다고 자랑하는 꼴밖에 되지 않는다.

- 모호한 관계

  • 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다. 독자가 주석과 코드를 읽고 무슨 소리인지 쉽게 알아야 한다.

- 함수 헤더

  • 함수를 길게 만들고 헤더를 다는 것보다, 함수를 작게 만들 연구를 하자.

- 비공개 코드에서 Javadocs

  • 비공개 코드에는 굳이 Javadocs를 달지 말자. 누가 읽을 것인가? 애초에 비공개인데.

 

반응형