Chapter 03. 주석과 코드 작성

 Point

많은 개발자 들이 주석을 경시하는 경우가 많이 있습니다. 하지만 주석은 소스코드 못지 않게 굉장히 중요한 역할을 합니다.

1. 주석은 필요한 내용만 간단히 서술하라
2. 코드를 주석을 달지 않아도 이해 할수 있도록 작성하라
3. 함수명으로 이해할 수 있는 내용을 구지 주석을 달지마라
4. 소스 및 코드는 들여쓰기를 해서 보기 간결하게 표시하라
5. 변수를 사용 할때는 수직으로 정렬하라

 

Content

프로그램을 개발 할 당시에는 자신의 소스코드를 주석이 하나 없어도 다 이해하고 있습니다.

하지만 몇 달이 지나고 몇 년이 지나서 다시 보게 된다면 지금과 같이 이해가 될까요?? 물론 불가능 합니다.

자신 뿐만 아니라 다른 사람이 볼 경우도 생기게 되는데 이때는 더욱 더 막막해 집니다.

그래서 주석 이라는 것은 꼭 작성을 해 주어야 합니다.

주위 몇몇 분은 전혀 주석을 달지 않는 분이 있는가 하면, 한편의 소설처럼 소스 코드 보다 주석이 더 긴 경우도

바왔습니다. 무엇이든 너무 적거나 지나치면 안한것만 못한 경우가 다반사 입니다.

 

주석을 자세히 달았는데 왜 좋지 않냐구요?? 만약 주석을 그 함수에 대해 일일히 한줄 한줄 다 설명해서 작성했다고

합시다. 만약 소스를 유지 보수 하게 될 경우, 수정한 소스코드에 해당하는 주석부분을 찾아서 일일히 다 수정해주어야 합니다.

이와 같이 오히려 소스 수정하는 시간보다 주석을 수정하는 시간이 더 들어 시간을 낭비하는 경우가 생길수 있기 때문입니다.

 

이제 주석 사용에 대한 예를 보시겠습니다.

1. 함수
2.       /*=====================================
3.         InsertNode
4. Function  : InsertNode                       <- 함수 이름
5. Prototype : void InsertNode( char *)    <- 함수의 프로토타입
6. Author     :  ChanSub Shin                 <- 작성자
7. Revision  : 1.0   2007.08.10 NEW          <- 최초 작성 날짜
8. Modified  : 2007. 08, 18 By ChanSub    <- 마지막 수정 날짜와 수정자
9. =====================================*/
10. void Node::InsertNode( char *node )
11. {
12. .....
13. }

2. 일반 소스

1.  if( *sBuf++ != *dBuf++ )        /* modified date : 2007.08.17 */
2. return 0;                        /* Not Equal */

 

첫 번째 방법은 함수위에 주석을 표시해서 첫 작성 날짜, 최종 수정 날짜, 작성자를 나타내며

두 번재 방법은 소스 옆에 그 코드에 대한 간단한 설명이나 수정한 날짜를 표시하는 것입니다.

 

이와 같이 사용하여 주석을 간결하고 그리고 깔끔하게 정리하고, 소스코드 도 마찬가지로

변수를 선언할때 코드를 TAB키를 사용하여 수직으로 줄을 맞춰서 선언 및 초기화를 해주는 것이 좋습니다.

그리고 for문이나 if문 등등에 for(int i=0;i<num;i++) 이런식으로 붙여 쓰는 경우가 많이 있는데 굉장히 읽기에

어렵습니다. for( int i = 0 ; i < num ; i++ ) 이와 같이 스페이스 바를 이용하여 적절히 띄워주어

같은 코드라도 좀더 이해하기 쉽도록 하는 것이 중요합니다.

 

헝가리언 표기법

표기법	의미	표기법	의미
a	배열	l	long 형 변수
b 또는 f	BOOL형 변수( b : bool, f : flag )	p	포인터 변수
by	BYTE( unsigned char ) 형 변수	lp	long 포인터 변수
c	카운터로 사용하는 변수	s	문자열
ch	char 형 변수	sz	널로 끝나는 문자열
cx, cy	x, y 길이를 나타내기 위해 사용하는 변수	u	unsigned int형 변수
d	날짜형 변수	w	WORD( unsigned short ) 형 변수
dbl	double 형 변수	dw	DWORD( unsigned long ) 형 변수
h	핸들( HANDLE ) 형 변수	str	CString 형 변수
n 또는 i	int형 변수	m_ , g_	멤버 변수, 전역 변수

 

프로그램의 시작시

1. /*+---------------------------------------------
2. **     Project Name       : ????
3. **     
4. **     File Name          : test.c
5. **     Revision           : 0.1
6. **     Date               : 2007.08.24
7. **     Author             : ChanSub Shin
8. **     Copyright (c) 2002 - 2003 ??? Co., Ltd
9. **     All Rights Reserved
10. +----------------------------------------------+*/

이 글은 스프링노트에서 작성되었습니다.