3. 코딩 스타일 3.2 코드의 문서화 3.2.2 주석 작성 스타일

3.2.2 주석 작성 스타일

어느 조직이든, 그 조직만의 주석 작성 방식이 있을 수 있다.

 

어떤 환경에서는 코드에 대한 공통적인 문서 표준으로서 특정 스타일의 주석을 강제하기도 한다.

 

어떤곳 에서는 주석의 스타일과 양을 전적으로 프로그래머 재량에 맡긴다.

---

3.2.2.1 모든 라인마다 주석 달기

충분한 문서화를 위해 소스 코드의 모든 라인마다 주석을 달 수도 있다.

 

모든 라인마다 주석을 달게 되면, 아무런 이유 없이 작성되는 코드를 피할 수 있다.

 

하지만, 대규모 프로젝트에 적용하기에는 무리가 있고, 코드가 지저분해지는 문제가 발생한다.

int result;						// 결과를 저장하기 위해 int 변수 선언
result = doodad.getResult(); 	// doodad의 결과 얻기
if ( result % 2 == 0) {			// 만약 결괏값의 mod 2가 0이면...
	logerro();					// 에러 발생을 기록
} else {						// 아니면...
	logSucces();				// 성공을 기록
}								// if/else의 끝
return result;					// 결과 리턴

위와 같은 주석작성은, 코드의 각 라인이 무엇을 하는지 자연언어로 설명한다.

 

이러한 주석은 전혀 쓸모가 없다.

C++의 기본지식을 가진 사람이라면, 코드만으로도 주석의 내용을 대부분 파악할 수 있기 때문이다.

if문이나, else에 대입된 주석은 프로그래머 라면 코드를 보면 주석을 보지 않고서라도 쉽게 이해가 가능하기 때문이다.

// Doodad를 계산합니다. 시작, 끝, 오프셋 값은
// "nDoodad API v1.6" 문서 96쪽 테이블을 참조합니다.
result = doodad.calculate(kStart, kEnd, kOffset);

// 성공 또는 실패를 결정하기 위해 결괏값과 프로세서 고유 마스크 
// ("Doodad API v1.6" 201쪽 참조)를 비트 단위 AND 연산합니다.
result = result & getProcessorMask();

// 사용자 필드값을 "Marigold 공식"
// ("Doodad API v1.6" 문서 136쪽 참조)에 맞춰 설정합니다.
setUserField((result + kMarigoldOffset) / kMarigoldConstant + kMarigoldConstant);

무슨 맥락에서 작성된 코드인 지는 알 수 없지만, 라인 단위 주석이 유용할 수 있는 좋은 예를 보여준다.

 

주석이 없다면 & 연산을 왜하는지 알 수 없고, 수식이 Marigold 공식에서 왔다는 것을 모를것이다.

---

3.2.2.2 머리말 주석

개발팀 차원에서 모든 소스 파일마다 파일 앞머리에 표준 포멧의 주석 작성을 원칙으로 정할 수도 있다.

 

이러한 주석은 프로그램이나 각 파일의 중요 정보를 기록할 수 있는 좋은 위치이다.

예를 들어 다음 항목들은 머리말 주석으로도 모든 파일에 포함시킬 수 있다.

• 최종 수정 날짜
• 원 저작자(개발자)
• 변경 이력
• 이 파일에서 구현하고 있는 기능의 관리 ID(feature ID)
• 저작권 정보
• 파일 또는 클래스의 개요
• 미구현 기능
• 알려진 버그

어떤 개발 툴은 파일마다 주석 템플릿을 자동으로 생성해주기도 한다.

---

3.2.2.3 고정 양식 주석

주석을 미리 정해진 양식에 맞추어 작성하고 별도의 문서 생성 툴은 이용하는 개발자도 많다.

 

java언어의 경우, javaDoc이라는 문서 생성 툴의 규약에 맞추어 주석을 작성하면 자동으로 HTML과 같은 하이퍼 링크 문서로 만들 수 있다.

 

C++에서는 Doxygen이라는 무료 툴이 같은 역할을 한다.

---

3.2.2.4 즉석 주석

대부분의 경우 그때그때 필요해서 주석을 작성하게 된다. 다음은 코드 중간에 주석을 기입해야 할 때 따라야할 가이드라인 이다.

• 비속어나 경멸적인 언어를 사용하지 않도록 최대한 노력한다.
• 조직 내에서 통용되는 농담은 별 문제가 안될때가 많다. ( 상급자에게 문의하자 )
• 작정자의 이름을 기입하지 않는다. 소스코드 관리 시스템에서 누가 수정했는지 이력을 관리한다.
• 의미가 명확하지 않은 API로 작업을 한다면 상세한 설명을 찾을 수 있는 참고자료를 표기한다.
• 코드를 업데이트할 때 주석도 같이 업데이트 해야 함을 잊어버리지 않도록 한다.
• 코드의 블록을 구분하는 용도로 주석을 사용했다면, 해당 코드를 별개의 함수로 분리하는것을 고려한다.

---

3.2.2.5 그자체로 이해가 충분한 코드

잘 작성된 코드는 많은 주석이 없어도 쉽게 이해할 수 있다.

 

가장 좋은 코드는 가독성 높은 코드이다.

만약, 각 코드 라인마다 주석을 추가하고 있다면, 주석 없이도 이해할 수 있도록 코드를 재구성해 보아야 한다.

 

C++도 결국 언어임을 잊지말아야 한다.

가독성 높은 코드를 작성하는 또 다른 방법은, 최대한 작은 부분으로 쪼개는것 이다.