•
이 장에서는 주석을 어떻게 명확하고 간결하게 작성하는지 살펴본다.
•
주석은 명확하게, 최대한 구체적이고 자세하게 작성해야 한다. 또한 간결해야 한다.
주석을 간결하게 하라
•
구구절절하게 적을 필요가 없다. 필요한 핵심만 전달할 수 있게 하자.
모호한 대명사는 피하라
•
구체적이지 않은 지칭은 오해와 혼돈을 불러온다. 명확하게 해라.
엉터리 문장을 다듬어라
•
문장을 복잡하게 만들지 마라.
◦
A했는지에 따라서 B한다보단 C했을때 B한다가 낫다.
◦
즉 문장을 복잡하게 만들어 읽는 사람을 헷갈리게 하지 말란 예시다.
◦
주석은 구체적인게 좋다.
함수의 동작을 명확하게 설명하라
•
메소드명에서 충분히 유추할 수 있는 내용을 반복하지 마라.
•
해당 메소드의 구현이 너무나 간단해 확인할 필요가 없을때, 주석을 달아서 그런 일을 하는구나.. 하는 정도로 하고 넘어가게 두어라.
코너케이스를 설명해주는 입/출력 예를 사용하라
•
주석을 작성하는데 신중하게 선택된 입/출력 예는 그 무엇보다도 좋다.
// 입력된 'src'의 'chars'라는 접두사와 접미사를 제거한다.
String strip(String src, String chars);
Java
복사
◦
이 주석은 chars가 제거되어야하는 부분 문자열인지 아니면 특정한 순서가 정해지지 않은 문자의 집합인지 알려주지 않는다.
◦
src의 끝에 chars가 여러번 있다면 어떻게 되어야하는가?
•
가장 좋은 방법은 입력과 출력을 신중하게 선택해서 주석으로 보여주는 것이다.
코드의 의도를 명시하라
•
주석 달기는 코드를 작성하면서 생각했던 바를 코드를 읽을 사람에게 전달해주는 것이다.
•
불행하게도 대부분의 주석은 새로운 정보를 제공하지 않고 수행하는 동작을 그대로 설명하는데 그친다.
•
구체적인 구현을 설명하는 것은 코드를 보게되는 시점에 크게 의미가 없어진다. 대신 도메인 언어로 설명을 해주면 더 좋을 것이다.
이름을 가진 함수 파라미터 주석
•
파라미터로 넘겨줄때 count(a, b)말고 count(a /* = 기존 값 */, b /* 카운트할 횟수 */) 이런식으로 하라는 것이다.
⇒ 솔직히 이렇게까지 해야할까? 싶었다..
정보 축약형 단어를 사용하라
•
특정한 문제가 반복될 때, 이런 패턴은 추상화시킬 수 있다. 즉 축약형 단어를 사용해서 표시할 수 있다.
요약
•
이 장에서는 간결함과 명확함을 주석에서 확보하는 방법에 대해서 알아봤다.
•
대명사가 여러가지를 가리킬 가능성이 있다면 사용하지 않는 것이 좋다.
•
함수의 동작을 실제로 할 수 있는 한도 내에서 최대한 명확하게 설명하라.
⇒ 동작이다 구현 아니다.
•
신중하게 선택된 입/출력 예로 주석을 서술하라.
•
코드가 가진 의도를 너무 자세한 내용이 아니라 높은 수준에서 개괄적으로 설명하라.
•
같은 줄에 있는 주석으로 의미가 불분명한 함수의 파라미터를 설명하라.
•
많은 의미를 함축하는 단어로 주석을 간단하고 명료하게 만들어라.
