효율적인 주석 달기

코드 수준 문서에서 가장 큰 공헌을 하는 것? 주석 이전에, 좋은 프로그래밍 방식이 필요하다.

-좋은 프로그램 구조

-직관적이고 이해가 쉬운 접근 방법의 이용

-좋은 변수 이름

-좋은 루틴 이름

-리터럴 대신 명명된 상수 사용

-명확한 배치

-제어 흐름과 데이터구조 복잡성 최소화

<주석에 대해>

-남이 달아놓은 주석을 너무 맹목적으로 믿지 말자. (서투르게 작성되기 쉬운게 주석이다.)

-추가적인 정보는 제공하지 않고 읽어야 하는 양만 늘리는 주석은 금물

-복잡하거나 어려운 코드를 주석으로 설명하려하기 보다는, 먼저 코드 자체를 명확하게 만들고 향상시키자.

-표시 주석에 '아직 구현되지 않음!' 과 같은 주석 금물. to do 같은 태그 이용

-코드를 한두줄로 요약하는 주석은 단순히 코드를 반복하는 주석보다는 훨씬 가치가 있다.

-많은 작업이 필요한 주석 작성 방식은 유지 보수 시 골칫거리다. (갱신되지 않은 주석은 정확하지 않거나 오해의 소지만 낳는다.)

-의사코드를 주석으로 작성하는 것도 좋은 방법이다. (코딩 전 사고가 명확해지고, 설계가 단순해지고, 코드 작성이 좀 더 직관적이고 주석은 자동으로 완성될 것이다.)

-성능 때문에 주석을 작성하지 않는다? -> 개발자 버전과 릴리즈 코드 버전을 다르게 생성하라. 툴 이용 등

-줄 끝 주석의 경우 대부분 이롭기보다는 해로운 경우가 많다. (예외, 데이터 선언, 블록의 끝 표시)

-단순 코드를 반복하는게 아닌, 코드 단락이 의도하는 바를 설명하는 주석은 관리도 쉽고 좋다.

-코드만 읽어서는 절대로 유추할 수 없는, 정보를 나타내는 주석은 좋다. ( //명령어 종결자($)를 찾는다.  >  // inputString에서 '$'를 찾는다. )

- // 만약 account flag가 0이라면,  이런 주석이 왜 필요한가? 필요없다. 코드 자체에서 이미 말해주고 있는 내용이다. ->//만약 새로운 계정을 만들어야 한다면,  ->//새로운 계정을 개설한다.

-생략하지 말기. 주석은 생략된 내용을 이해하려는 노력없이 명백하고 읽기 쉬워야 한다. 매우 일반적인 생략을 제외하고는 생략을 하지 않아야 한다.

- 메이저 주석(//테이블에 있는 문자열을 복사한다.)   마이너 주석(//...테이블에 있는 문자열의 수를 결정한다.)

-언어와 개발 환경에서의 오류나 문서화되어 있지 않은 기능에 관한 내용을 주석으로 작성한다(예를들어, blockSize가 500인 경우에 대해서 특별히 처리한 이유에 대한 기록을 남긴다던가)

-입력 데이터의 한계를 주석으로 작성하라.

-비트 수준의 플래그는 반드시 문서화한다.

-전역 데이터를 문서화한다. 

-Javadoc과 같은 코드 문서화 유틸리티를 활용하라