[완료] 적당한 주석에 대한 여러 의견을 듣고 싶습니다.

[추가글]
어떻게 주석을 달아야 할 지 오랜 고뇌 끝에
Doxygen 방식을 주석 가이드라인으로 삼게 되었습니다.

질문 코드 case 중 case 1만 Doxygen 방식으로 올려둡니다.

case1(Doxygen 방식)
/**
@return bool : 정상 작동시 true, 아닌 경우 false

@param src_num : 2진 바이너리로 출력 할 값

@brief 10진수 값을 2진수 비트 단위로 출력한다.

@todo 예외 처리 미완
*/
bool DisplayNumToBit(unsigned int src_num) {

//해당 자료형의 비트 갯수 구하기
unsigned int cnt_bit = sizeof(src_num) * 8;

//비트 MSB오프셋 설정
unsigned int bit_offset = 1 << (cnt_bit-1);

//모든 비트 마스크 비트 갯수
unsigned int total_cnt_bit = cnt_bit;

//MSB 부터 최하위까지 반복
for (int i = 1 ; i <= total_cnt_bit ; i++) {

//비트 마스크 연산
if (src_num & bit_offset) {

putchar('1');
}
else {

putchar('0');
}

//8비트 단위로 공백 간격 출력!
if (0 == (i % 8)) {

putchar(' ');
}

bit_offset = bit_offset >> 1;
}

putchar('\n');

return true;
}

=========================================
=========================================
[질문]
주석에 대해 여러 견해가 있더군요.
어떤 의견은 '네이밍을 잘하면 주석은 최소한으로 해도 된다'란 주장과
'아니다 무조건 해야된다' 두가지가 있군요.
코드는 다른 사람이 봤을 때 이해가 잘되게 가독성 있게 짜는게 중요하지 않습니까?

회사에 따라 존재하는 코딩 컨벤션을 참고해도 주석에 대해서는 자세한 가이드가 없고
오픈소스 몇개 봤는데 다 가지각색이군요.

그래서 주석을 달면서 계속 의문이 들어서 제 코드를 올려봅니다.
다른 사람이 보기 편한 코딩을 하라고 하는데 제 코드가 보기 편한지 또한 궁금합니다.

3가지 케이스에 대해 고칠 점 말해주시면 감사하겠습니다.

=========================================
=========================================
case 1:

함수명에 대한 자세한 설명을 함수 위에 해준다.
(과한 걸까요? 아니면 더 나은 함수 설명 주석 방법이 있을까요?)

//------------------------------------------------------------------------
//
// 10진수 값을 2진수 비트 단위로 출력 함수
//
// 첫 번째 인자는 10진수 값
// 두 번째 인자는 진수 변환 및 출력 할 2진수 비트의 단위
// TODO 예외 처리 미완
//------------------------------------------------------------------------------
bool DisplayNumToBit(unsigned int src_num) {

//해당 자료형의 비트 갯수 구하기
unsigned int cnt_bit = sizeof(src_num) * 8;

//비트 오프셋 설정
cnt_bit--;
unsigned int bit_offset = 1 << (cnt_bit);

//최상위 비트 부터 비트단위 출력
//8비트 단위로 출력 간격 둠
unsigned int total_bit = cnt_bit + 2;
for (int i = 1 ; i < total_bit ; i++) {

if (src_num & bit_offset) {

putchar('1');
}
else {

putchar('0');
}

if (0 == (i % 8)) {

putchar(' ');
}

bit_offset = bit_offset >> 1;
}

putchar('\n');

return true;
}

=========================================
=========================================
case2:

모든 로직에 대해 주석은 최대한 보이게 큼지막하게 써준다.
(주석이 코드 로직보다 더 많은 내용을 차지하는데 이게 옳은 걸까요??,
오히려 코드 가독성을 해쳐서 버그가 더 생기지 않을까요??)

while (1) {

//------------------------------------------------------------------------------
// 키보드 값 입력
//
// 사용자가 음수를 입력 할 경우가 존재가능
// 입력값은 long타입으로 받자
// 만일 unsigned int형으로 -1입력 받으면 0xffffffff가 되버리는 참사가 일어난다
//------------------------------------------------------------------------------
long tmp = 0;
puts("비트로 표현 할 값 입력(unsigned int형 범위 내) : ");
scanf_s("%u", &tmp);

//------------------------------------------------------------------------------
// 예외 처리 : 입력 값 유효성 체크
//------------------------------------------------------------------------------
if (tmp < 0 || tmp > UINT_MAX) {

puts("잘못된 유효숫자 입력, 다시 입력하세요\n");
continue;
}
//정상적인 유효숫자 입력한 경우
else {

//unsigned int형으로 타입 캐스팅!
src_num = (unsigned int)tmp;
}

//------------------------------------------------------------------------------
// 10진수 값을 2진수 비트 단위로 출력
//------------------------------------------------------------------------------
if (DisplayNumToBit(src_num)) {

puts("성공!\n");
}
else {

puts("실패!\n");
}
}
}

=========================================
=========================================
case 3

모든 클래스 내부 멤버에 대한 지나치게 자세한 설명 주석

class CTextParser : StringManager
{
private:

//------------------------------------------------------------------------------
// 버퍼 사이즈 설정
//
// :파서 대상 텍스트 최대 읽기 가능 사이즈
//------------------------------------------------------------------------------
typedef enum BUF_SET{
BUF_SIZE = 1000
}BUF_SET;

//------------------------------------------------------------------------------
// 파서 대상 텍스트 경로
//------------------------------------------------------------------------------
char _textPath[100];

//------------------------------------------------------------------------------
// 현재 프로바이더 셋 여부
//
// :현재 검색 가능 프로바이더 범위가 설정된 경우 true
//------------------------------------------------------------------------------
bool _bProvider;

//------------------------------------------------------------------------------
// 시작 프로바이더 공간 포인터
//
// :텍스트 파서 대상에서 읽어온 버퍼 내 해당 프로바이더 내부 공간 시작 주소
// :프로바이더 내부 기호'{' 이후의 버퍼 주소
//------------------------------------------------------------------------------
char *_ptr_provider;

//------------------------------------------------------------------------------
// 현재 프로바이더 명
//------------------------------------------------------------------------------
char _provider_name[100];

//------------------------------------------------------------------------------
// 버퍼 선언
// 입력받은 텍스트 길이 선언
//------------------------------------------------------------------------------
char _text_buf[BUF_SET::BUF_SIZE];
int _cnt_char;// 텍스트 길이

=========================================
=========================================
읽어주셔서 감사합니다.