TIL (Today I Learned) 날짜

2022.04.29

오늘 읽은 범위

4장. 주석

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

• 주석은 오래될수록 코드에서 멀어지고, 완전히 그릇될 가능성도 커짐->유지보수 어려움.

• 코드만이 자기가 하는 일을 진실되게 말한다.

•  

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

-코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문, 차라리 코드를 정리해야함.

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

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

• 좋은 주석: 정말로 좋은 주석은 주석을 달지 않을 방법을 찾아낸 주석이다.

• (1)법적인 주석

-(ex)각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 소유권 정보는 필요하고 타당함.

• (2)정보를 제공하는 주석: 이왕이면 이것도 함수 이름에 정보를 담는 편이 좋다.

• (3)의도를 설명하는 주석

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

-모호한 인수나 반환값 자체를 명확하게 만들면 더 좋겠지만, 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면, 주석이 유용

• (5)결과를 경고하는 주석

-(ex)특정 테스트 케이스를 꺼야하는 이유를 설명하는 주석

• (6)TODO 주석

-요즘 대다수 IDE는 TODO주석 전부를 찾아보여주는 기능을 제공하므로 주석을 잊어버릴 염려는 없다.

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

• (8)공개 API에서 Javadocs

• 나쁜주석

• (1)주절거리는 주석

-특별한 이유 없이 의무감으로/프로세스에서 하라고 하니까 마지못해 주석을 단다면 시간낭비

-주석을 달리고 결정했으면 충분한 시간을 들여 최고의 주석을 달도록 노력해야함

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

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

• (4)의무적으로 다는 주석

• (5)이력을 기록하는 주석

-소스코드관리시스템으로 관리됨

• (6)있으나 마나 한 주석

-너무 당연한 사실 언급, 새로운 정보 제공못함

• (7)무서운 잡음

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

• (9)위치를 표시하는 주석

-배너 남용시 독자가 흔한 잡음으로 여겨 무시함

• (10)닫는 괄호에 다는 주석

-차라리 함수를 줄이려고 시도하자.

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

-소스코드관리시스템에 저장하는 편이 낫다.

• (12)주석으로 처리한 코드

-주석으로 처리한 코드는 사람들이 다른 사람들이 지우기를 주저한다. 나중에 너무 많이 쌓임.

• (13)HTML 주석

-HTMLwntjrdms 편집기/IDE에서조차 읽기 어렵다. 주석에 HTML 태그를 삽입하는 것은 도구가 져야한다.

• (14)전역 정보

-코드 일부에 주석을 달면서 시스템 전반적인 정보 기술하지 말 것.

• (15)너무 많은 정보

• (16)모호한 관계

-주석과 주석이 설명하는 코드는 둘 사이 관계가 명확해야함.

• (17)함수 헤더

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

• (18)비공개 코드에서 Javadocs

-시스템 내부에 속한 클래스와 함수에 Javadocs를 생성할 필요 없음. Javadocs 주석이 요구하는 형식으로 인해 코드가 산만해짐

• (19)예제

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

• 주석을 왠만하면 달지 말 것. 주석을 달 바에는, 주석의 내용을 포함할 수 있는 코드를 작성하자.