소스 코드 주석 다는 법

오늘의 포스팅 주제는 프로그램 주석 다는 법입니다.

소스 코드에 주석은 왜 달아야하는걸까요?

프로그램을 계속 짜다 보면 덩치가 큰 것들은 무지하게 소스코드가 길어집니다. 소스 코드를 수정하다 보면 몇 달 몇 년이 지난 코드를 수정하게 될 수도 있는데 너무 많이 만들다 보니 까먹는 경우가 있습니다. 어제 마신 술도 기억이 안 나는데 어찌 1년 전 코드를 기억을 할까요? 주석을 통해 이를 해결할 수 있습니다.

프로그램은 다음 사람이 알아보기 쉽게 작성을 해야 하며, 여러 사람이 하나의 프로젝트를 하는 경우 코드를 분석하는 데 주석을 통해서 시간을 단축시킬 수 있습니다. 

사람마다 주석 다는 방법이 다 다르겠지만 저는 세세한 설명은 //을 사용하고 있고 그 외엔 아래와 같은 방법으로 주석을 달고 있습니다.

함수의 경우

/** @brief 함수의 설명

*  @date 함수 업데이트 날짜

*  @return 리턴값에 대한설명

*  @param 함수의 인자 설명

*/

메인 페이지

/**

*@mainpage 메인페이지 제목

*@brief 요약설명

*@details 자세한 설명

*/

파일 주석

/**

*@file NewClass.cpp

*@brief 간략

*@details 상세

*/

패키지 주석

/**

*@namespace org.nhnnext

*@brief 간략

*@details 상세

*/

클래스 주석

/**

*@brief 간략

*@details 상세

*@author Name, Name@tistory.com

*@date 2019-06-09

*@version 0.0.1

*/

class ClassName

{

   /* do nothing */

}

함수의 주석을 다는 경우 예제

예시로 확인하는 것보다 예제를 통해 확인해보는 게 낫겠죠? 이전에 포스팅 했던 UTF8 -> 유니코드 변환 함수를 예제로 들어보겠습니다. 만약 param이 여러 개인 경우 여러 개를 쓰면 됩니다.

/** @brief UTF8을 유니코드로 변환해줌.
*  @date 19/06/09
*  @return UTF8toUnicode : 변환된 유니코드 값.
*  @param num : 변환하려는 UTF8의 인덱스.
*/
uint32 UTF8_Type_Check(uint8 num)
{
    uint32 UTF8toUnicode = 0;
    uint8 UTF8_byte = UTF8_Byte_table[buff[num]];
 
    switch (UTF8_byte) {
        case 4:    
            UTF8toUnicode += (buff[num++] & 0x07); UTF8toUnicode <<= 6;
            UTF8toUnicode += (buff[num++] & 0x3f); UTF8toUnicode <<= 6;
            UTF8toUnicode += (buff[num++] & 0x3f); UTF8toUnicode <<= 6;
            UTF8toUnicode += (buff[num] & 0x3f);
            UTF8toUnicode = 4;
            break;
 
        case 3:    
            UTF8toUnicode += (buff[num++] & 0x0f);     UTF8toUnicode <<= 6;
            UTF8toUnicode += (buff[num++] & 0x3f);     UTF8toUnicode <<= 6;
            UTF8toUnicode += (buff[num] & 0x3f);
            UTF8_Byte_val = 3;
            break;
 
        case 2:    
            UTF8toUnicode += (buff[num++] & 0x1f); UTF8toUnicode <<= 6;
            UTF8toUnicode += (buff[num] & 0x3f);
            UTF8_Byte_val = 2;
            break;
 
        case 1:    UTF8toUnicode += buff[num];
            UTF8_Byte_val = 1;
            break;
    }
 
    return UTF8toUnicode;
}

이상으로 주석을 열심히 달아서 다음 사람도 소스 코드를 보기 쉽게 만들고 자신이 만든 함수의 용도가 무엇인지 까먹는 일이 없도록 하시길 바랍니다.