개발자 99% 커뮤니티에서 수다 떨어요!
오늘 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
jhb1356님의 TIL (url 링크)