2장 기초

2.10 명명규칙

언어의 기능을 만들어내거나 대체하기 위해 명명 규칙을 사용하기도 한다.

var PI = 3.14;
var MAX_WIDTH = 800;

__getName(); // private
_getName(); // protected

2.11 주석작성

문제에 깊이 몰입해 있을 때에는 코드가 어떤 일을 하느지가 명백히 보이는 것 같지만, 대개 일주일 후에 다시 코드를 들춰보면 코드의 동작을 정확히 기억해내는데 곤란을 겪게 된다.

뻔한 내용에 과도하게 주석을 달라는 게 아니다. 하지만 일반적으로 모든 함수의 매개변수와 반환 값에 대해서는 문서화할 필요가 있다.

2.12 API 문서작성

JSDoc & YUIDoc 자세한 내용은 책 참조

2.22 독자를 위한 문서작성

모든 작가와 편집자가 교정의 중요성을 강조한다.

…

종이 위에 뭔가를 써내려가는 것은 첫 걸음이자 초안에 불과하다. 초안도 독자에게 정보를 전달하긴 하지만 가장 명확하고 구조적이고 읽기 쉬운 방식이라고 하긴 어렵다.

…

기대되는 결과를 만들어냈다 해도, 어느 정도 시간이 흐른 다음에 코드를 다시 들춰보면 대부분의 경우 개선할 여지가 눈에 띌 것이다.

어떻게 하면 좀 더 읽기 쉬워지겠다거나, 일부 비효율적인 부분을 삭제해야겠다는 식으로 말이다.

이것이 본질적으로 교정의 과정이며, 고품질의 코드라는 목표에 크게 기여한다.

…

그렇기 때문에 API 문서 작성이 교정의 기회가 된다.

종종 문서 주석 블록을 작성하면서 문제를 재발견하게 된다. 예를 들어 메서드의 세 번째 매개변수가 사실상 두 번째 매개변수보다 더 자주 필요하고, 두번째 매개 변수는 기본값이 대부분 true라고 하자. 그렇다면 인터페이스를 살짝 변경하여 두번째와 세번째 매개변수를 맞바꾸는게 더 말이 될 것이다.

“하나는 버릴 계획을 세워라”라는 말도 있다. 처음 떠오른 해결책은 동작은 할지 몰라도 그저 초안일 뿐이며 해결책의 한 예시에 불과하다. 문제에 대해 좀더 깊이 이해한 상태에서 나오는 두 번째 해결책이 항상 더 낫다. 두번째 해결책을 만들 때는 첫번째 해결책을 복사해와서 붙여넣는 것을 금지해야 한다.