TIL (Today I Learned)

2022.02.24

오늘 읽은 범위

4장. 주석

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

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

• 주석은 순순하게 선하지 못하다. 진실은 한곳에만 존재한다. 바로 코드다

• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다

#좋은 주석

• 법적인 주석

• 정보를 제공하는 주석

• 의도를 설명하는 주석

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

• 결과를 경고하는 주석

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

• 중요성을 강조하는 주석

#나쁜 주석 - 일반적으로 허술한 코드를 지탱하거나, 엉성한 코드를 변명하거나, 미숙한 결정을 합리화한다

• 주절거리는 주석

• 같은 이야기를 중복하는 주석 - 주석이 코드보다 더 많은 정보를 제공하지 못하고, 코드보다 읽기가 쉽지도 않다

• 오해할 여지가 있는 주석

• 의무적으로 다는 주석

• 이력을 기록하는 주석

• 있으나 마나 한 주석 - 있으나 마나한 주석을 달려는 유혹에서 벗어나 코드를 정리하라

• 무서운 잡음

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

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

• 닫는 괄호에 다는 주석 - 작고 캡슐화된 함수에는 잡음일 뿐이다. 함수를 줄이려 시도하자

• 공로를 돌리거나 저자를 표시하는 주석 - 소스 코드 관리 시스템 누가 언제 무엇을 추가했는지 기억한다. 그냥 코드를 삭제해라

• HTML 주석 - 편집기/IDE에서조차 읽기가 어렵다

• 전역 정보 - 근처에 있는 코드만 기술하라. 시스템의 전반적인 정보를 기술하지 마라

• 너무 많은 정보 - 흥미로운 역사나 관련없는 정보를 장황하게 늘어놓지 마라

• 모호한 관계 - 주석과 주석이 설명하는 코드는 둘 사이 관계가 명확해야한다.

• 함수 헤더 - 짧은 함수는 긴 설명이 필요없다. 함수에 한가지만 수행하며 이름을 잘 붙이자

• 비공개 코드에서 Javadocs - 공개하지 않을 코드라면 Jacadocs는 쓸모가 없다

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

• 주절거리는 주석이나, 위치를 표시하는 주석, 있으나 마나한 주석 등을 보면서 주석을 잘못 달고 있었다는 것을 알게 되었다.

• 특히 코드를 삭제한 후에 그 코드가 다시 쓰일까봐 주석으로 처리할때가 많았는데 소스 코드 관리 시스템을 믿고 삭제해야겠다.

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

• 함수의 이름을 붙일때 기능을 알수 있게 하기 위해 짓다보면 너무 길어져서, 차라리 주석을 달아야겠다는 생각이 드는데 어떻게 행동해야할까??