'Code convention'에 해당되는 글 1건

1. 개요
개발과 관련된 code convention과 naming rule에 대해 기술한다.

2. 필요성
  2-1. 소프트웨어 생명(Life Time)의 80%는 유지 / 보수에 소요된다.
  2-2. 소프트웨어의 가독성을 향상시킨다.
  2-3. 본래의 개발자에 의해서 소프트웨어 개발 전체가 유지되는 소프트웨어는 거의 존재하지 않는다.

3. 함수
  3-1. 기본 규칙
     * MainCategory_SubCategory1SubCategory2VerbObject1Object2
     * 예)
              - Log_OpenLogSystem() : modules/Log의 로그시스템 생성 함수
              - DB_TrieDBNew() : modules/DB/TrieDB의 생성 함수
  3-2. Verb 동사가 나오기 전까지는 카테고리를 표현
  3-3. Verb 동사는 어떤 기능을 하는지 표현
  3-4. Object는 특정 목적 대상이 있거나, 특별하게 구별하고 싶을 때
  3-5. 동사든 명사든 첫 글자는 대문자로 표기
  3-6. MainCategory가 첫 자가 대문자인 경우는 라이브러리(modules 디렉토리)에서, 소문자인 경우는 App 자체 (apps 디렉토리) 모듈
     * 예)
            - Pthread_Create() : 라이브러리(modules/Pthread)에 소속된 모듈로써, thread를 생성하는 함수
            - ppr_Create() : 라이브러리에 소속되지 않은 모듈로써 ppr 자료구조를 새롭게 생성하는 함수
            - static void _CheckLogFileSize() : _(언더바)로 시작하는 함수는 선언한 파일 안에서만 통용되는 함수로써 그 의미를 명확하게 하기 위해 static으로 선언.
  3-7. 다소 길어도 명확하게 - 의미 전달이 명확하게
  3-8. 생성자의 경우엔 "_Create", 소멸자인 경우엔 "_Destroy", 초기화의 경우엔 "_Init" 사용
      * 예) ppr_Create();, ppr_Destroy();, ppr_Init();
  3-9. File 쓰기엔 "_Write", 읽기엔 "_Read" 사용
  3-10. File read 시 첫번재 item 읽을때 "_ReadFirst", 그 다음 item 읽을때 "_ReadNext" 사용
      * 예) ppr_Write();, ppr_Read();, ppr_ReadFirst();, ppr_ReadNext();
  3-11. 구조체 object에 값 setting 할때 "_Put", 값 불러올때 "_Get" 사용
      * 예) Parameters_PutItem();, Parameters_GetItem();
  3-12. 통상적으로 사용하는 연산이 있는 경우는 그대로 사용한다.
      * 예) Queue_enQueue();, Queue_deQueue();, Stack_Push();, Stack_Pop();

4. 변수
  4-1. 헝가리안 표기법 사용
     *  헝가리안 표기법에 대한 분분한 의견이 있지만, C/C++에서 이만큼 의미를 명확히 표현해주는 표기법이 없다.
     * Format
       * x_xXxxxxxx
       * 0123456789
       * 0 : 변수의 위치를 지정한다. g(전역변수), m(멤버변수), 없음(지역변수)
       * 1 : 0 위치에 g 나 m을 지정한 경우 "_"를 기술
       * 2 : 자료형의 종류
       * 3 ~ : 변수의 의미있는 이름을 기술. 3 위치는 대문자를 사용, 변수 이름이 너무 긴 경우 자음만을 기술.
  4-2. Table

prefix	type	description	example
b	bool	any boolean type	bool bTrue;
c	char	character type	char cLetter;
i	int	integer for index	int iCars
n	int	number, quantity	int nNum;
l	long	long type	long lDistance;
u	unsigned	unsigned type(4byte)	unsigned uPercent;
w	WORD	unsigned word(2byte)	WORD wCnt;
dw	DWORD	unsigned double word(4byte)	DWORD dwLength;
d	double	double floating point	double dPercent;
f	float	floating point	float fPercent;
s	static	a static variable	static short ssChoice;
rg	array	stands for range	float rgfTemp[16];
p	*	any pointer	int iAddr;
sz	*	null terminated string of characters	char szText[16];
pfn	*	function pointer	int (*pifnFunc1)(int x, int y);
t	struct	a user defined type
e	enum	variable which takes enumerated values
E	struct	a user defined type
g_	Global	Global Variable	String *g_psBuffer;
m_	Member	class private member variable	int m_iMember;
k	constant formal parameter		void vFunc(const long klGalaxies)
r	reference formal parameter		void vFunc(long &rlGalaxies)
str	String	string class(C++)	String strName;
prg		dynamically allocated array	char *prgGrades;
h	handle	handle to something	hMenu
x/y		used as size	int xWitdth, yHeight;

  4-3. Example
      * int g_nCnt;  : 정수형 글로벌 카운터
      * unsigned char ucByte;  : 한 바이트 데이터
      * char cChar;  : 한 문자
      * unsigned char rgucByte[10];  : 바이트 데이터 10개
      * char rgcChar[10];  : 문자 데이터 10개
      * char szChar[16 + 1]; : 문자 16개를 저장할 수 있는 문자열 공간
      * Etc
         * typedef로 재정의된 자료형일 경우 t_를 prefix로 사용
            * 예) unsigned char t_UC
      * Attention
         * 포인터(*) 및 참조(&)는 변수의 앞에 붙여서 선언
            * int * piAddr; -> int *piAddr;
      * Exception
         * 일반적으로 사용하는 변수 i, j, argc, argv는 그대로 사용한다.
         * C 라이브러리의 종속적인 변수 type일 경우, 일반적으로 사용하는 변수명을 사용한다.
           * 예)
              * phtread_t *tid (pthread_t가 unsigned int임에도 불구하구...)
              * phtread_attr_t *attr;

5.  구조체
  5-1. 기본 규칙
     * Maincategory_Name
  5-2. 첫 자만 대문자 (매크로와의 구분을 위해...)
  5-3. 예) Socket_Context (Socket의 Context에 사용되는 구조체)

6.  매크로
  6-1. 기본 규칙
     * MAINCATEGORY_SUBCATEGORY_NAME
  6-2. 대문자만을 사용
  6-3. 예) TKIR_INDEX_METHOD_BLOCK

7. 파일 생성규칙
  7-1. 하나의 디렉토리에 디렉토리를 대표하는 인터페이스용 헤더파일이 한 개 존재해야 함.
  7-2. 각각의 모듈 내부에서만 사용하는 함수를 인터페이스에 노출시킬 필요 없음.
  7-3. 헤더파일
      *. 중복 참조 방지용 매크로를 정의한다.

#ifndef __PTHREAD_H__ #define __PTHREAD_H__ #endif

  7-4. C++을 위하여 다음을 선언한다.

#ifdef __cplusplus extern "C" { #endif #ifdef __cplusplus } #endif

8. 기타
  8-1. 리턴 값
     * 일반적으로
       * 0 : 성공
       * 음수 : 실패
       * 양수 : 오류는 아니지만, 기타 정보를 돌려줄 때
  8-2. 들여쓰기 (개인적인 취향에 따르도록)
     * 4칸이나 8칸. 경험상 4칸이 적절하나 개인적인 취향이니 적절히
  8-3. 칼럼 (개인적인 취향에 따르도록)
     * 될 수 있으면 80 칼럼을 지키는 것이 가독성 향상

9.  문서화
  9-1. 위키 (문서 작성)
     * 최소한 관련 모듈에 대해선 위키에 기본 내용이라도 작성한다.
  9-2. doxygen (documentation)
     * doxygen을 이용하여 문서화를 기본으로 한다.
     * 기본적인 format인

/** @brief 함수 관련 설명 @param pArg1 첫 번째 함수 인자에 대한 설명 @param pArg2 두 번째 함수 인자에 대한 설명 @return 0 : success -1 : fail */

이 형태를 유지하고, 나머지 format은 권고 사항이다.

     * 참조 URL : http://wiki.kldp.org/wiki.php/Doxygen