명확하고 간결한 주석 달기
더스틴 보즈웰, 트레버 파우커
느낌표 ! (인상 깊은 문장 | 문맥)
엉터리 문장을 다듬어라
주석을 명확하게 하는 작업과 간결하게 하는 작업은 대부분 한번에 이루어진다.
# 이 URL 을 전에 이미 방문했는지에 따라서 다른 우선순위를 부여한다이 문장은 어느정도 괜찮지만, 다음 문장과 비교해보자.
# 전에 방문하지 않은 URL 에 높은 우선순위를 부여하라.p.93
첫 번째 든 예시에서 뭔가 더 나은 문장이 생각나지 않았는데 아래의 개선된 문장을 보니까 여지없이 깔끔함 그 자체의 문장이다. 부족함이 더욱 느껴져서 다행이기도 하다.
코너케이스를 설명해주는 입/출력 예를 사용하라
// 입력된 'src'의 'chars'라는 접두사와 접미사를 제거한다. String Strip(String src, String chars) {...}…
// 예: Strip("abba/a/ba", "ab")은 "/a/"를 반환한다. String Strip(String src, String chars) {...}p.95
필자의 경우 이 인용구를 읽고 딱 떠오르 코드가 있어 수정하였다. 년월일자를 출력하기 위해서 moment 를 사용한다.
export function momentLL(value: string | Date) {
return moment(value).locale('ko').format('LL');
}
문제는 나중에 보니 LL 포멧이 무엇을 출력하는지 기억이 나지않아 코드를 찾아서 상황을 보거나 official docs 를 살펴봐야했다. 그렇지만 주석을 달 생각을 하지 못했었다가 저 인용구를 보고 떠올라 수정하였다. 아래와 같이 수정하였다. 입출력 값 예제가 있으니 무엇을 출력하는지 한 눈에 알아볼 수 있게 되었다.
물론 아래 2개의 함수는 하나로 합칠 수 있다. 다른 부분엔 format 만 다르기 때문이다.
/*
ex 2022.08.20.
*/
export function momentL(value: string | Date) {
return moment(value).locale('ko').format('L');
}
/*
ex 2022년 8월 20일
*/
export function momentLL(value: string | Date) {
return moment(value).locale('ko').format('LL');
}
문장으로 설명을 잘하는 것도 중요하지만 프로그래머는 코드로 서로 이야기하듯 입출력 예시로 코드를 파악하는데 매우 큰 도움을 줄 수 있을 것이다. 잠깐 생각만해도 개발하다 레퍼런스를 보기 위해서 해당 함수를 들여다보면 입출력 예제가 있는 것을 적지 않게 볼 수 있다.
읽기 좋은 코드가 좋은 코드다는 정말 와닿게 예제를 너무 잘 만든 것 같다. 이번 책 리뷰가 끝나면 마틴 파울러의 리펙토링을 리뷰하려하는데 리펙토링 또한 깊이 고민안해도 한 눈에 무엇이 좋은 코드인지 알 수 있다. 저번 글에서도 적었지만 이러한 수준까지 올라오기 위해서 얼마나 많은 노력과 열정이 있었을지 감도 오지 않는다. 개발자로서 품고 있는 말이지만 클린코드를 작성하는 개발자가 되고싶다.
Chapter 6 느낌
Chapter 6 에서는 좋은 주석을 달기 위한 강력한 팁을 알려주고있다.