TIL (Today I Learned)

2022.02.24~25

오늘 읽은 범위

4장. 주석

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

• 나쁜 코드에 주석을 달지 마라. 새로 짜라. - 브라이언 W. 커니핸, P.J. 플라우거

• 잘 달린 주석은 그 어떤 정보보다 유용하다. 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다. 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다.(68p)

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

• 부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다.(69p)

• 진실은 한곳에만 존재한다. 바로 코드다. 코드만이 자기가 하는 일을 진실되게 말한다. 코드만이 정확한 정보를 제공하는 유일한 출처다.(69p)
  

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

  • 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다. 자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는 데 시간을 보내라!

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

• 좋은 주석

  • 법적인 주석

  • 정보를 제공하는 주석

  • 의도를 설명하는 주석

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

    • 모호한 인수나 반환값을 명확하게 만들면 더 좋겠지만, 인수나 변환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.(72p)

  • 결과를 경고하는 주석

  • TODO 주석

  • 중요성을 강조하는 주석

  • 공개 API에서 JavaDocs

• 나쁜 주석

  • 주절거리는 주석

    • 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다.(76p)

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

  • 오해할 여지가 있는 주석

  • 의무적으로 다는 주석

    • 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없다. 이런 주석은 코드를 복잡하게 만들며, 거짓말을 퍼뜨리고, 혼동과 무질서를 초래한다.(80p)

  • 이력을 기록하는 주석

  • 있으나 마나 한 주석 (너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석이다.) (81p)

  • 무서운 잡음

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

  • 위치를 표시하는 주석

  • 닫는 괄호에 다는 주석

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

  • 주석으로 처리한 코드

  • HTML 주석

  • 전역 정보

  • 너무 많은 정보

  • 모호한 관계

    • 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.(89p)

  • 함수 헤더

    • 짧은 함수는 긴 설명이 필요 없다. 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.(89p)

  • 비공개 코드에서 Javadocs

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

• '나쁜 주석'에 대해 읽으면서 난데..? 라는 생각이 들었다. 이렇게 배웠으니 이게 당연하다고 생각했다. 그래도 더 늦기 전에 깨달을 수 있어서 다행이다. 오래된 소스를 볼때 구석구석 주석이 달려있는 것을 많이 접했었다. 볼때마다 주석을 별 의미없이 지나쳤거나, 모호한 관계를 가진 주석과 코드를 너무 많이 겪어 불신하며 바로 코드를 분석했던 경험이 많았다. 나쁜 주석이었다니.. 난 그저 보이는 그대로만 흡수했었다. 이게 잘못 된 것이었음을 깨닫는 장이었다.

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