Community

개발자 99% 커뮤니티에서 수다 떨어요!

← Go back
[TIL] 4장. 주석
by xgro
#clean_code
2년 전
642

오늘 TIL 3줄 요약

  • 잘 달린 주석은 그 어떤 정보보다 유용하다.

  • 프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면, 주석은 거의 필요하지 않으리라.

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

TIL (Today I Learned) 날짜

2022. 04. 29.

오늘 읽은 범위

4장. 주석

책에서 기억하고 싶은 내용을 써보세요.

  • 잘 달린 주석은 그 어떤 정보보다 유용하다.

  • 주석은 쉰들러 리스트가 아니다. 주석은 ‘순수하게 선하지’못하다.

  • 사실상 주석은 기껏해야 필요악이다.

  • 프로그래밍 언어 자체가 표현력이 풍부하다면, 아니 우리에게 프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면, 주석은 거의 필요하지 않으리라. 아니, 전혀 필요하지 않으리라.

  • 불행하게도 주석이 언제나 코드를 따라가지는 않는다. 아니, 따라가지 못한다.

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

    • 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.

  • 코드로 의도를 표현하라!

    • 몇 초만 더 생각하면 코드로 대다수 의도를 표현할 수 있다. 많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.

  • 좋은 주석

    어떤 주석은 필요하거나 유익하다. 하지만, 명심하기 바란다. 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이라는 사실을!

    • 법적인 주석

      • 모든 조항과 조건을 열거하는 대신에, 가능하다면, 표준 라이선스나 외부 문서를 참조

    • 정보를 제공하는 주석

      • 때로는 기본적인 정보를 주석으로 제공하면 편리하다.

    • 의도를 설명하는 주석

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

    • 결과를 경고하는 주석

      • 다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용한다.

      public static SimpleDateFormat makeStandardHttpDateFormat()
      {
      	// SimpleDateFormat은 스레드에 안전하지 못하다.
      	// 따라서 각 인스턴스를 독립적으로 생성해야 한다.
      	SimpleDateFormat df = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z");
      	df.setTimeZone(TimeZone.getTimeZone("GMT");
      	return df;
      }
      

      더 나은 해결책이 있다고 불평할지도 모르겠다. 하지만 여기서는 주석이 아주 합리적이다.

    • TODO 주석

      • ‘앞으로 할 일’을 //TODO 주석으로 남겨두면 편하다.

    • 중요성을 강조하는 주석

  • 나쁜 주석

    대다수 주석이 이범주에 속한다.

    • 주절거리는 주석

      저자에게야 의미가 있겠지만 그 의미가 다른 사람들에게는 전해지지 않는다.

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

    • 오해할 여지가 있는 주석

    • 의무적으로 다는 주석

    • 이력을 기록하는 주석

    • 있으나 마나 한 주석

    • 무서운 잡음

    • 위치를 표시하는 주석

    • 닫는 괄호에 다는 주석

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

    • 주석으로 처리한 코드

    • HTML 주석

    • 전역 정보

    • 너무 많은 정보

    • 모호한 관계

    • 함수 헤더

    • 비공개 코드에서 Javadocs

오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요

  • 주석 작성시 맨처음 서술된 내용은

    프로그래밍 언어 자체가 표현력이 풍부하다면, 아니 우리에게 프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면, 주석은 거의 필요하지 않으리라. 아니, 전혀 필요하지 않으리라.’

    이다. 위 내용을 토대로 이 단원을 읽으려고 노력했다.

  • 하지만, 그럼에도 불구하고 주석이 필요한 상황을 적절하게 제시해준 점이 너무 좋았다.

  • 주석이 필요한 시점, 필요하지 않은 시점에 대한 내용과, 예시가 시의적절하게 기술되어 추후 프로그래밍 언어 작성시 참고할 내용이 더욱 풍부해졌다.

궁금한 내용이 있거나, 잘 이해되지 않는 내용이 있다면 적어보세요.

오늘 읽은 다른사람의 TIL