오늘 TIL 3줄 요약

• 나쁜 코드에 주석을 달지마라. 새로 짜라.(p.68)

• 우리는 (간혹 필요할지라도) 주석을 가능한 줄이도록 꾸준히 노력해야한다.(p.69)

• 코드로 의도를 표현하라!(p.70)

TIL (Today I Learned) 날짜

2022. 04. 29.thur

오늘 읽은 범위

4장.주석

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

• 나쁜 코드에 주석을 달지마라. 새로 짜라.(p.68)

• 우리는 (간혹 필요할지라도) 주석을 가능한 줄이도록 꾸준히 노력해야한다.(p.69)

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

  -자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는 데 시간을 보내라!

• 코드로 의도를 표현하라!(p.70)

  -주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.

• 좋은 주석(p.70~75)

  1) 법적인 주석 ex) 저작권 정보, 소유권 정보

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

  3) 의도를 설명하는 주석

  4) 의미를 명료하게 밝히는 주석 ex)모호한 인수나 반환

  값

  5) 결과를 경고하는 주석 - 테스트 케이스일 경우 @Ignore 속성을 이용해 구체적인 설명을 문자열로 넣어준다.

  6) TODO주석 - 앞으로 할 일을 //TODO 주석으로 남겨두면 편하다.

  7) 중요성을 강조하는 주석

• 나쁜 주석(p.75~94)

  1) 주절거리는 주석 - 이해가 안 되어 다른 모듈까지 뒤져야 하는 주석은 독자와 제대로 소통하지 못하는 주석이다. 그런 주석은 바이트만 낭비할 뿐이다.

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

  3) 오해할 여지가 있는 주석

  4) 의무적으로 다는 주석 - 오히려 코드만 헷갈리게 만들며, 거짓말할 가능성을 높히며, 잘못된 정보를 제공할 여지만 만든다.

  5) 이력을 기록하는 주석, 공로를 돌리거나 저자를 표시하는 주석, 주석으로 처리한 코드 - 소스 코드 관리 시스템을 이용하자

  6) 있으나 마나 한 주석(너무 당연한 사실을 언급해 새로운 정보를 제공하지 못하는 주석) - 있으나 마나 한 주석을 달려는 유혹에서 벗어나 코드를 정리하라. 더 낫고, 행복한 프로그래머가 되는 지름길이다.

  7) 무서운 잡음 - 함수나 변수로 표현할 수 있다면 주석을 달지 마라.

  8) 위치를 표시하는 주석 - 반드시 필요할 때만, 아주 드물게 사용하는 편이 좋다.

  9) 닫는 괄호에 다는 주석- 닫는 괄호에 주석을 달아야겠다는 생각이 든다면 대신에 함수를 줄이려고 시도하자.

  10) HTML 주석

  11) 전역 정보 - 주석을 달아야 한다면 근처에 있는 코드만 기술하라.

  12) 모호한 관계 - 주석과 주석이 설명하는 코드는 둘 사이에 관계가 명백해야 한다.

  13) 함수 헤더 - 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.

  14) 비공개 코드에서 Javadocs - 공개 API는 Javadocs가 유용하지만 공개하지 않을 코드라면 Javadocs는 쓸모가 없다.

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

• 나는 지금까지 좋은 주석보다는 나쁜 주석을 사용했다. 함수헤더, 닫는 괄호에 다는 주석, 있으나 마나한 주석 등 내가 단 주석은 코드가 좋은 코드가 아니여서 그랬나보다. 주석을 달아야겠다는 생각이 듣다면 대신 함수를 줄이고, 코드를 정리해야겠다.!

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

• 무서운 잡음?

• 의무적으로 다는 주석은 오히려 코드만 헷갈리게 만들며, 거짓말할 가능성을 높히며(?), 잘못된 정보를 제공할 여지만 만든다.