주석은 어떻게 다는 것이 가장 좋을까요?

geekforum의 이미지

많은 분들이 각자 나름대로 주석을 다는 스타일을 하나씩은 가지고 계실 겁니다.

정말 중요한 부분에만 간략하게 다시는 분이 있을 것이고, 매 함수마다 파라미터와 리턴값에 대해서도 다시는 분도 있겠죠. 정말 매 줄마다 빽빽하게 채우시는 분도 계실 것으로 믿습니다.

다들 서로 생각하시는 장단점이 있을 것 같군요. 실력 & 경력있는 분들의 주석 다는 비법(?)을 감히 여쭙습니다.

PS> 언어마다도 차이가 어느 정도 있을테니 여기서는 C/C++로 한정했으면 합니다.

댓글

트론의 유령의 이미지

저의 코딩 스타일 입니다만...


#include //////////////////////////////////////////||
#include // ||
#include // 프로그램에서 쓰일 헤더파일들 선언부분 ||
#include //________________________________________||
#include "struct.h"

//--------------------------------------------------------------//

/*---------[ 게시판 프로그램 파일처리에 필요한 함수들 ]---시작--*/
//||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
// ||
// int FileAdd( BOARD *board) -> BOARD 사이즈만큼 파일에 저장 ||
// ||
//||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
int FileAdd( BOARD *board)
{

FILE *fp;

if( (fp=fopen("data.dat","ab")) == NULL )
{

fprintf(stderr,"Error\n");
return 0;

}

fseek( fp, 0 , SEEK_END );
fwrite(board , sizeof(BOARD) , 1 , fp);
fclose(fp);
return 1;

}

//||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
// ||
// long filesize(FILE *) -> 파일의 길이(사이즈)를 구하는 함수 ||
// ||
//||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
long filesize(FILE *stream)
{

long curpos, length;
curpos = ftell(stream);
fseek(stream, 0L, SEEK_END);
length = ftell(stream);
fseek(stream, curpos, SEEK_SET);
return length;

}

//||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
// ||
// int GetRecordNum(FILE *) -> 파일에 저장된 레코드 갯수 구하기 ||
// ||
//||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
int GetRecordNum(FILE *f)
{

long fsize=filesize(f);
int num=fsize/sizeof(BOARD);
return num;

}

//||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
// ||
// long FileGoto(FILE *,int) -> 현재 위치로 파일 커서를 이동 ||
// ||
//||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
long FileGoto(FILE *f , int num)
{

long pos=num * sizeof(BOARD);
long newpos=fseek( f , pos , SEEK_SET );
return newpos;

}

//||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
// ||
// int FileGetRecord(FILE *,int,BOARD *) -> 해당 블록을 읽어 옴 ||
// ||
//||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
int FileGetRecord(FILE *f , int num , BOARD *b)
{

FileGoto(f , num);
fread( b , sizeof(BOARD) , 1 , f );
return 0;

}
/*----------[ 게시판 프로그램 파일처리에 필요한 함수들 ]----끝--*/

//--------------------------------------------------------------//

//||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
// ||
// int Input_String_Width_Chk( char *data, int min, int max ) ||
// ||
// => min , max 값을 수치로 지정하여 입력 최소/최대 길이 지정 ||
// ||
//||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
int Input_String_Width_Chk( char *data, int min, int max )
{

int length;
int i;

length = strlen(data);

if( length < min ) {

printf("

\n");
printf("입력크기 허용 최소치에 미달했습니다!! \n");
exit(0);
printf(" \n");

}

else if( length > max ) {

printf("

\n");
printf("입력크기 허용 최대치를 초과했습니다!! \n");
exit(0);
printf(" \n");

}

}

익명 사용자의 이미지

저도 전문적 프로그래머는 아니기에 주석은 이렇게 달아라 라고 말할 수는 없습니다.
다만 저의 경험을 토대로 주석에 대한 오해 점에 대해 이야기 할까 합니다.

첫째, 주석은 자세하게 써야 한다.
과연 그런가여?
저의 경우, 왠만한 소스 분석을 할때 주석 때문에 시간이 더 걸리더군요. 대부분의 소스는 영어로 주석이 되어 있는 게 많고 프로그램 처음부터 한 20-30 라인은 기본으로 파일에 대한 설명하면 기타 이래 저래 하나 설명이 죽 나오는데 그거 읽다가 지쳐서 소스 분석 포기하는 사람들도 많습니다. 뭐 좀 경력이 된다면 뭐 그 정도는 대강 짐작으로 넘어 가고 프로그램의 핵심을 공략할 수 있겠지만 다른 프로그래머가 다 그럴 수는 없는 거 아닙니까?

둘째, 주석은 빠짐없이 써야 한다.
이 점 또한 동의 할 수 없는 것 중 하나. 소스를 볼때 이건 저거의 포인터라고 한 수십줄이 나옵니다. 그냥 간단히 프로그램 초반에 이 변수는 이 변수의 포인터 라고 간단히 한 줄 짜리 주석이면 될 것을.. 아니면 변수명을 줄 때 ptr_변수 이런 형식으로 딱 정해서 프로그램 하면 오히려 주석 다는 것 보다조 좋지 않을 까여?

결론이 벌 써 부터 나와 버렸네요...
저의 경우 주석을 별로 좋아 하지 않습니다.
주석달다가 일이 엄청 늦어 지더군요.
전 그보다 프로그램 내에서 변수명 함수명 기타 name들을 명명할때
일정한 규칙을 주고 그 규칙에 맞추어 프로그램 하는 걸 좋아 합니다.
그리고 소스엔 주석을 거의 넣지 않습니다.
변수나 함수에 대해 하고 싶은 말이나 남기고 싶은 말은 대부분
헤더 화일 넣어 버립니다.
(자바의 경우는 인터페이스에)
그렇게 하는 게 남들이 내 프로그램 보면서 같이 작업 하는 과정에서도
시간도 절약되고 좋습니다.
아무리 이쁘게 코딩 되고 주석 잘 단 소스라고 해도
남의 소스를 본다는 거 그 자체가 짜증 스러운 일 아닙니까?
그래서 전 아에 소스를 볼 필요도 없게 끔 headr화일을 사용합니다.
많은 분들이 이 헤더 화일을 사용하지 않거나 간과하시는 경우가 있더군요.
처음에 프로그램 배울때 의 습관인거 같습니다.
프로그램을 조금 힘들게 배우신 분들은 그 중요성을 조금이나마 이해 하실수 있을 겁니다.

이런 제가 쓰고도 제가 무슨 말을 했는지...

그럼 이만.

익명 사용자의 이미지

잘 짜여진 프로그램은 주석이 필요없다.
아니 있으면 가독성만 더 떨어질 뿐이며, 오해의 소지도 있다.

그러나......
프로그램을 잘 짜는 사람이 그리 많진 않다.
대부분의 사람들은 로직조차 바르게 구현하지 못한다. 그래서 논리적 버그를 만든다. 스스로 로직테스트도 안해본다. 실제로 SI 쪽의 소스를 보면 쓰레기와 같다는 느낌을 받을 수도 있다.
그냥 돌아가면 된다는 식의 엉망인 소스도 많다.
쓸데없이 함수 call하는 경우도 많다. 여러 개 중첩된 함수를 따라 다녀보라.. 열받는다. 게다가 함수에 대한 적절한 설명도 없다면? 보는 사람이 열받는 건 당연하다. 실제로 나중에 보니 최적화와는 거리가 먼 무조건 돌아가면 된다는 식의 소스였다.

그래서 주석을 달아야 한다. 자신의 머리를 과신할 때 버그가 생기는 것이다. 주석을 달다 보면 버그도 잡힌다.
때로는 처음부터 주석으로 시작한다.
의사코드를 이용해서 로직을 구현한 후, 상세부분을 스터핑하는 것이다. 이렇게 하면 로직 상에 버그는 대부분 제거된다.

주석을 제대로 잘 달지 않거나 못다는 사람은
1. 대부분 자신의 소스에 자신이 없는 사람들이다.
2. 아니면 다른 사람이 못보길 바라는 마음이던가.
4. 그 소스는 죽어도 혼자만 쓸 거라던가.
5. 주석 다는 걸 배운 적이 없거나.
6. 자기가 아는 걸 남도 다 알거라고 생각하는 바보거나.
7. 시간이 모자라던가......

7. 번의 경우가 발생하긴 한다. 그러나 그건 프로그래밍하는 마음자세를 바꾸면 해결된다. 실제로 의사코드 + 스터핑에 의한 방법과 무작정 코딩에 의한 방법을 보면 확실히 전자가 빠르다는 것을 알 수 있다. 실제로 소스코드가 200 이상 되면 그렇다. 내 경험이다. 물론 내 프로그램이 가진 버그는 다른 사람들이 만든 것보다 십분의 일 정도 수준이다. 주석을 다는 시간은 전체 소스 중에서 5 % 도 안될 것이다. 시간이 모자르다고 주석을 간과한다면, 나중에 그 몇 배의 디버깅 작업을 해야 하고, 10 시간을 걸려서라도 논리적 오류를 찾아 다녀야 할 것이다. 물론 이런 경우에 따로 만드는 게 빠를 때가 많다.

주석은 간단하게, 정확하게, 로직을 타야 한다.
그리고 어떤 분이 API 나 라이브러리에 대해서 주석을 달아야
한다고 했는데, 그게 언어 자체에 존재하는 거라면 주석을 달
필요가 없다고 생각된다.. 왜냐면 그건 당연히 알고 있는 것으로 여겨져야 한다. memset() 같은 함수에 대해서 주석을 다는 것은
자습서에서나 쓰면 된다.

마지막으로,
좋은 주석은 주석만으로도 프로그램을 다시 짤 수 있다.!!!
나도 아직 못하는 바이지만....

익명 사용자의 이미지

1.공간상 분류.

1.1 모듈 별 주석 : ???
1.2 파일 별 주석 : version 관리 툴에서 지원하는 형식으로..
대개 보면(제가 봤던 소스-별로 많진
않지만), 저위의 난이아빠 님이 쓰신 방식이
많더군요..
하지만, history는 파일의 맨끝에 위치하는
편이 훨씬 더 소스를 보기에는 좋더군요.
하지만, 파일 별 history를 보기에는 난이아빠
님께서 쓰신 방법이 좋겠더군요.

대부분의 version 관리 툴에서 history를 넣는
위치를 정할 수 있는 것으로 압니다.

1.3 변수,함수,class, : 제 경우에는, 다른 사람들이 사용하는
library 작업을 했기 때문에, 다른 사람들에
게 배포작업과 함께 변경 사항을 개별적으로
알려주다보면, 수정시간 보다 의사소통시간이
더 많이 걸리더군요... ^^;
아예 documentation 툴을 써서, 제 com에
현재 소스의 변경 사항을 html로 검색 가능
하도록했는데, 역시나 쓰는 사람이 없어서,
개발 완료 보고서 쓰는데만 사용했지요.
사용했던 툴은, 위에 어떤분이 JavaDoc을 사용
해 보셨다던데, 전 Doc++, Doxygen을
쓰다가 마지막에는 Doc++으로 낙찰을 봤습니
다. 형식은 JavaDoc과 같구요.
(주석 넣는 형식 중에 JavaDoc Style과
Qt style이 있다고 합니다. 개인적으로는
JavaDoc style을 더 좋아하죠...)
지원되는 기능은, C++ Class hierarchy viewer,
html/tex output, see also, 함수 리턴값,파라
미터 값 설명,등등이 있습니다.
다음 번에는 Doxygen을 써보려하는데, 바빠서..

개발 com에 web server, documentation tool,
html document들로 서비스 하면서, 의사소통
시간을 줄이려 했는데, 역시나, 팀플이 우선..

1.4 알고리즘,꽁수 : 제 경우에는 알고리즘 및 꽁수가 사용된
블록의 바로 위에 주석을 붙이고, (미리 조금
설명을 보고 코드를 보기 쉽게 하려는 의도 및
copy&paste하기 쉽게 하려는 의도)
소스 쪽의 줄끝 주석은 되도록이면 사용하지
않습니다. 오히려,소스 보는데 방해가 되더군요.
(특히, vim, 80 col에서는 ^^;)

2. 시간상 분류
아직까지 저 또한, source 주석에 관한 history의 개정에
관한 노하우가 많이 쌓여 있지 않아서, 뭐라 말씀 드리기
어렵군요.
대개 버젼별, 버그별로 개정을 수행하는것이 좋을 듯 합니다.

버그별 개정은 반드시 그 history가 남아 있어야 다음 사람이
똑같은 삽질을 안하게 되지요.. 특히 팀플에서는..

그럼..

익명 사용자의 이미지

어느정도 프로젝트 경험이 쌓인 회사나.

탄탄한 조직체계가 있으면.

주석부터 변수 정의서 까지 만들고 쓰는걸로 알고 있습니다.

재미 삼아 만든 변수 이름하나에..

머리 지끈거리는건 당연한 결과 겠지요...^^

이상 잡담 이었습니다.

익명 사용자의 이미지

무진장 중요할테죠..
코딩하는 자의 룰과 프로그렘의 구조를 알수 있는 설명인데..
제가 인격수양이 좀 덜되고 전에 당기던 회사도 구라만발이고해서
c로 만들었던 코드들을 나올때 달아놨던 주석들을 싸그리 지우고
나왔던 격이 있는데.. - -;;
지금생각해보면 인젠 쪼금이나마 인격수양이 되었는지
쫌 미안하고.. 걸 맡은분 고생했을 생각하믄 마니 미안하고..

익명 사용자의 이미지

저는 얼마전부터 C로 프로그램 짤때는 cweb 을 씁니다.
http://www-cs-faculty.stanford.edu/~knuth/cweb.html
에 보시면 자세한 설명이 나와 있읍니다.
TeX 에 자신 있으시면 한번 써보시는것도 괜찮겠지요.
문제는 쓰는 사람들이 거의 없어서 여럿이서 함께 프로그램
짤때 좀 문제가 될듯 하네요.
그래도 좀 익숙해지고 나니 이보다 좋은 주석(?)은 없는듯 합니다.
C++ 도 쓸수 있고요. Java 도 된다는 말을 들었는데 그건 잘
모르겠고...

다타만의 이미지

상당히 철학 적인 문제가 아닌가 생각됩니당..

주석이란 남이 보기 편하게 하기위해서 (사실 거의 본인이 볼일이 많지만 ㅠ.ㅠ)

전에 어떤 고수가 만드신 소스를 봤는데.. 주석을 보고 프로그램의 흐름을 읽을수있게 되어있더군엽

저같은 경우야.. 평션 설명과.. 변수 설명 (규칙에 따르지 않는 경우)

루틴 중요한 의미를 갖는 제어문 에다가..쓰는데엽

머.. 대충 아래 많은 다른분들과 같은 곳이네엽 ^^;;

이렇게 밖에 말할수 없지만..

내가 아닌 다른 사람이 보아도 편해야 겠져..물론 자기가 볼 코드라도 3년후 현재의 나와는 다른 사람이 되어있을수도 있으니깐여..

저는 의식적으로 좀 자세히 다는편입니다.

함수 호출부, 함수내부 시작부, 조건문등에엽 ^^

익명 사용자의 이미지

익명 사용자의 이미지

주석에도 여러가지 방법이 있겠지만, 일단은 if, while등의 함수 열고 닫는 것도 여러가지 방법이 있군요. 성격상 가끔은 모두 내 style로 고치고 싶은 충동을 받을때가 많군요.
예를 들어서

(ex1)
if(a==b)
{
......
}

(ex2)
if (a== b){
.....
}

(ex3)
if ( a == b )
{
}

이런 것이 마구 섞여있는 project를 하게되면 마구 짜증이나고 통일하자고 하고 싶은데 그리고 사실 회사마다 ISO로 규정된 정규form이 있지만 일부 code는 다른 곳에서 가져오고 하니 다 정의 될 수도 없고....

{}의 위치나 (..)안의 사용이 다른 것이 아마도 주석이 깨끗이 통일되기는 어려운 것은 암시하는 것 같네요. 한국 리눅서만이라도 통일이 어떻게 안되려나?

익명 사용자의 이미지

번역본이 출간되어 있음을..
친절히 ISBN 까지 달아주셨는데..
오해를..-.-
TPOP 는 문서라기보단 책입니다 -.-

익명 사용자의 이미지

이런 -_-;
저 밑에 리플단다는게 이런 실수를..-_-;

익명 사용자의 이미지

익명 사용자의 이미지

: 이건 HTML 주석이군요.. ^^;

익명 사용자의 이미지

주석을 다는 이유는 많이 있겠지만...
제가 알고 있는 것은...
누가 보더라도(언어를 모르는 사람이라도..)...
주석만으로 로직을 파악할 수 있도록 하라는 것입니다...

때로는 상당히 불필요하고 귀찮은 작업같지만...
점점 덩치가 커져나가는 코드들을 유지보수 하기 위해서는..
어느정도 시간과 비용을 절감할 수 있는 방법이기도 합니다...

저 같은 경우에는...
보통 코드의 시작부분에 목적,기능,argument 리스트,output 등을
코멘트하고...
함수 부분에도 기능, in/out parameter 등을 간략히 코멘트 합니다
물론 함수명으로 쉽게 기능 파악을 할 수 있는 경우나...
짧은 코드는 생략할 때도 많습니다...

변수 선언부에도... 임시 루프 변수 등을 제외하고는...
대부분 코멘트를 해 놓구요...
필요한 경우에는 변수의 scope 도 코멘트 합니다...

그리고 복잡한 알고리즘이나 로직이 사용된 부분에는...
반드시 그 내용들을 코멘트 합니다...
사용된 알고리즘이 뭐고 알고리즘은 어떤식으로 진행되고 하는...
루틴들을 코멘트 해 놓습니다...

제가 처음 코딩을 배울때에는...
제일 먼저... 제가 짤 프로그램의 주석을 미리 적어 놓고..
그 내용에 따라 코딩을 하곤 했었습니다...
논리 구조 및 로직의 파악이 용이 하기 때문에...
나름대로 괜찮은 방법이었다고 생각합니다...

주석 다는 스타일이야 많이 있겠지만...
/////////////////
나..
/****************
등으로 이쁘게? 꾸미는 것은 좀 귀찮을 것 같다는 생각이 드네요^^
한눈에 들어오니깐 알아 보기는 쉽겠지만...
제가 너무 게으른 탓에.. ^^;;

가능한한 /* */ 사이에 깔끔하게 때려넣는 스타일을 선호합니다.

다른 많은 분들의 얘기도 도움이 많이 되었습니다.. :)
좋은 하루 되십시요...

익명 사용자의 이미지

저도 지금 SI쪽에서 일을 하는 사람입니다.
대부분의 소스코드에 주석을 넣고 있습니다. 첨 이일을 할때.
복잡한 소스코드에 주석한줄 없어 소스코드가 간단한건 별문제가 없었는데 반해 복잡한 루틴을 가진 소스코드는 과연 이게 뭐하는건가 분석하는데.. 상당한 애를 먹은 적이 있습니다...물론 다들 한번씩은 경험해보셨을겁니다...
그래서 요즘은 주석을 다는것을 습관적으로 아래처럼 해주고 있습니다..

/* 20010509 지나가는행인
수정이유: 고객의 변태적인 요구에 맞도록
쿼리 수정: 역시 고객의 변태적인 요구에 맞도록
함수 수정: 이건 말도 안되는 요구를 처리 하기 위해
정상적으로 작동하는 함수를 사용할수 없어
수정함..
참고사항 : 프로그램내에서 쿼리가 복잡해진 이유
고객사의 변태적인 DB를 현재 진행중인 프로그램에
맞게 가져오기위해 어쩔수가 없음...^^
*/

뭐 전부다 이런식으로 주석을 다는건 아니지만.. SI업체에서 일하시는 분들은 이해하시라 생각됩니다...

익명 사용자의 이미지

전 개인적으로 주석 많은 코드를 싫어합니다. 잘 짜여진 코드는 주석이 필요없다고 생각하거든요. 물론, 아예 없는 게 좋다는 건 아니고, 최소한으로 줄일 수록 좋다는 겁니다. 주석은 절대 다다익선이 아닙니다.
특히나 객체지향 언어로 프로그래밍을 할 때는 클래스들을 잘 정의하고 그 클래스의 역할과 메쏘드에 대해서만 약간의 주석을 달아주면 충분하죠. 그리고, 메인 프로그램에 그 프로그램에 대한 전체적인 주석을 달아주고요. 보통, 한 메쏘드가 15라인 이내라면 주석 없이도 금방 이해할 수 있습니다. 노가다 코드가 들어간 경우는 15라인은 넘겠지만 이런 경우도 코드는 노가다로만 한정하면 역시 길어도 금방 이해할 수 있을 꺼구요. 15라인이 넘어간다면 그 기능을 작은 다른 메쏘드를 만들어서 호출해서 해결해야겠죠. 물론, 함수를 여러번 호출하는 게 퍼포먼스를 떨어뜨릴 수 있지만, 소스 코드의 유지보수에서의 장점과 비교할 수는 없습니다. 아니면 인라인 함수를 쓰는 방법도 있고.. 아뭏든 클래스 외부에서 접근하는 public 함수에만 간략한 주석을 달고 나머지는 작은 protected나 private 함수로 분할하는 것이 이해하기도 쉽고 나중에 수정할 때도 어디를 수정해야하는가를 찾기 쉽죠. 이런 게 유닉스의 개발 철학이기도 하죠. 사실 아주 잘 짜여진 객체지향 프로그램은 주석이 거의 필요가 없습니다. 이게 객체지향의 강력한 장점 중 하나이기도 하죠. 그래서, gcc도 디폴트가 C에서 C++로 어서 바뀌어야 한다고 생각합니다. g++을 입력하는 것도 꽤 귀찮거든요.--;
물론 변수명이나 함수명을 잘 짓는 건 필수입니다. 변수명, 함수명을 짓는 일반적인 규칙을 잘 따르면 나중에 코드를 보기가 훨씬 편합니다. 비주얼 씨 같은 경우는 헝거리안 표기법으로 표준화가 잘 되어 있는데 리눅스는 변수명, 함수명에 대한 표준화가 부족한 듯 하더군요. 썬에서 권장하는 자바의 표기법과 비주얼 씨에서 많이 쓰는 헝거리안 표기법을 조합하면 상당히 괜찮으리라고 보는데..물론 변수명이 꽤 길어지겠지만..--;

익명 사용자의 이미지

제가 써본 프로그래밍 언어들이... 모두 영어로 되어 있네요...
그래서... 변수명 길게 주고... 영어 문장과 거의 같게 해주어도...
역시나....
어쩔 수 없이 "한글"로... 주석을 달게 된답니다.
(오로지 '나'와 우리 겨레를 위해 주석을 다는 것입니당~)

하지만, 함수, 조건문, 루프문의 시작과 끝에서는....
주석을 달지 않을 이유도 없고, 나중에 저도 모르는 경우가 가끔 있어서...
자주 다는 편입니다.
(이건 내 코드를 볼 모든 사람을 위해서...)

익명 사용자의 이미지

물론 상대적으로 단순한 알고리즘을 구현하며 상위 객체일 수록
주석의 필요성이 줄어들겠지요.

하지만 알고리즘이 좀 복잡해지거나 (분리하기 힘든)
하위 수준의 객체로 내려갈 수록 최적화의 필요성 때문에
코드는 알아보기 힘들겁니다.

특히 MFC 같은 frame work 위에서 프로그래밍할 경우에는 당연히
주석의 필요성이 줄어들 수 밖에 없습니다.
하지만 MFC의 소스를 보신적이 있으신지요. 과연 코드 그대로
설명이 되는 코드라고 생각하시는지요?
(저는 MFC가 잘 만들어졌다고 생각하는 사람입니다)

주석은 다다익선은 아니지만, 최소한으로 줄이는 것도 아니라고 생각합니다.
필요한 곳에 '충분하게' 넣어야한다고 생각합니다.
그리고 정확하게 넣는 것도 중요하겠죠.

그리고 public interface에만 주석을 단다고 하셨는데,
interface 사용자에게는 문제가 없겠지만,
object의 유지보수는 어떻게 하나요?

특히 공동작업을 할 경우, 아무리 간단한 함수라도
주석을 다는 것이 좋다고 생각합니다.
만든 사람에게는 지극히 간단하더라도 다른 사람에게는
이해하는데 오래 걸릴 수도 있습니다. 단지 실력탓이 아니라요.
훨씬 효율성을 높힐 수 있습니다.

익명 사용자의 이미지

잘 설계되고 구조화된 프로그램에 주석이 많을 필요가 없다는 건 동감하지만 그게 객체 지향의 장점이라는 건 좀 이상하군요. 오히려 모호하기 쉬운 객체간의 관계에 대한 서술이 필수적인 객체지향이 좀 더 많은 주석을 필요로 하지 않을까요.
그리고 make를 쓰시면 g++ 입력하실 것도 없고 정 안되면 aliasing을 하면 되고요.

gcc의 디폴트가 c인 이유는 여기(http://www.gnu.org/prep/standards_7.html#SEC7)에 나와 있습니다.

When you want to use a language that gets compiled and runs at high speed, the best language to use is C. Using another language is like using a non-standard feature: it will cause trouble for users.

그냥 C++이 최고인 것처럼 말씀하시니까 뿔따구 나서 딴지 걸었습니다...^^;

익명 사용자의 이미지

소스 분석을 몇번 하다 보니 역쉬 주석의 불편함을 느끼게 됩니다.
특히 많은 소스의 주석이 대부분 주석의 의미를 상실하지 않나 싶어요.
제 생각에는 필요없는 주석은 삭제하고, 각 함수의 기능과 설명 등이
주가 되어야 하지 않을 까 싶네요.

주석다는 것도 일이지만.. 보는 사람은 고통 스러워서.

익명 사용자의 이미지

반대의 경우도 있답니다.
단순 변수... i, j, k는 ... 루프문에서...
"무엇"을 카운팅 하는지 설명해 주지 않는 경우가 많아요.
그런데, 그 "무엇"에 대한 설명이 없으면...
이해하기 힘든 알고리듬도 가끔 있네요.

저처럼 실력이 부족한 이들을 위해서라도...
꼭 루프문에서는.... 주석을 달아주세요.
종료조건, 카운팅 변수가 카운팅 하는 것, 카운팅 작업의 의미 등등...

익명 사용자의 이미지

잘 짜여진 소스에 많은 주석이 필요할까요. 기독성 자체는 소스와
주석중 소스가 차지하는 비중이 더 큰거죠. 소스에서 함수와 변수이름을 잘 만드는것 자체가 주석을 대체할 수가 있죠. 파라미터와 리턴값도 마찬가지 아닌가요. 그러나 일반 어플에서까지 그런 주석들은 불필요하며 오히려 짜증나더군요.

API 나 라이브러리는 필히 주석을 달아야겠죠.

park_의 이미지

/*
start
*/

/*
end
*/

// 병이야..-_-;

익명 사용자의 이미지

에~~~~~
뻥치고 있어!

#include ...
으로 시작해서...

}
로 끝나는 park 의 소스들...

ㅡㅡ;

익명 사용자의 이미지

에이~~
더 뻥치고 있네여...

#include
{
...
}

이렇게 되는게 아닌가요?

{ 이게 빠졌네요...ㅡㅡ;

익명 사용자의 이미지

하하하

익명 사용자의 이미지

뭐... 프로그래머라고 말하면, 사람들이 비웃는

공부하는 학생인데요..

경력이고 뭐고 별로 없지만, 그래도 한줄 적어 볼까 합니다.

저는 함수 프로토타입 선언할때, 그 옆에 죽 적어주고..

상수선언 했을때, 그 옆에 죽 적어주고..

전역변수들에 달아주고..

쫌 복잡하다 싶은 루프에 달아주고..

꽁수 부린데 있으면, 달아주고...

그러고 보니... 주석 안다는 데가 없네여...ㅡ,.ㅡ;

익명 사용자의 이미지

저의 주석처리는 다음과 같습니다...

제가 주로 SI쪽에 있어서 그런지 이런식의 주석처리를 사용합니다..^^

/**
* 프로젝트명 : 리눅스 클릭 한번에 인스톨하기
* 발주처 : Open Source Project
* 기간 : 2000.01.01 ~ 2100.12.31
* 작성자 : 난이아빠 baram4x@kernel.pe.kr (TEL : 0xx-xxxx-xxxx )
*
* 파일명 : OneClick.cc
* 파일 설명 : 사용자의 클릭 이벤트를 받아서 한방에 모두 주변기기를
* 인식하고 자동으로 환경설정 후 사용자가 원하는 최적의
* 환경을 제공하도록 처리하는 부분.
*
* 참고사항 : 절대 M$ 제품을 같이 사용하지 마시길..^^
*
* 버전 내역
* ---------- ------------------------------------------
* 2001/05/08 최초 버전 작성 0.0.1 작성자 난이아빠
*/

/**
* 기능설명 : 자동으로 주변기기 인식
* 함수명 : AutoDetectDevice
* 인자설명 : void
* 넘겨주는 값 : true - 정상처리됨.
* false - 처리중 오류발생.
*
*/

/**
* End of File
*/

익명 사용자의 이미지

저같은 경우는 프로그램 시작부분에
/*********************
*
* 소스 설명
*
*********************/

이렇게 하구요,
각종 function에 그 function에 대한 주석 조금
그리고 변수에 대한 주석

그리고 흐름에 대한 주석이 필요하다 싶을때 적습니다.
주석이 많으면 가독성이 떨어질 수 있다는 의견이 많던데요,
제 의견은 좀 다릅니다.
저역시 주석을 효과적으로 달아가며 작업하지는 못합니다만,
예전에 디센트라는 게임의 소스(공개되었죠)를 살펴본적이
있습니다. 그 대부분의 소스에는 많은 주석들이 붙어있었죠.
아주 조그마한 모듈 하나하나 마다 전부 주석이 달려있었고,
소스가 100줄이라면 거의 50줄 이상의 주석이 붙어있었습니다.
그런데 보기에 상당히 편하게 되어있더군요.

단락에 구분을 지어서 그 모듈들에 대한 설명이 잘 되어 있었던
것으로 기억합니다.

주석을 잘 다는것 역시 상당한 정성이죠...
어렵구요...^^

Renn의 이미지

주석은 불필요할 경우를 제외하곤 많이 넣는것이
좋다고 하지요?
그렇지만, 너무 많은 경우는 오히려 가독성을 떨어뜨리는 것
같습니다. 정당히 한 문맥이 뭐하는 것이다 라는 것만
적어놔도 내부 코드 분석할 실력이면 충분하리라 생각되네요.

물론, 함수나 클래스 같은 것에 대한 상세한 설명은
필수겠지요. ;;

익명 사용자의 이미지

이미 보셨는지 모르겠지만 아래글들을 추천합니다.

The Practice of Programming (Addison-Wesley)
GNU Coding Standards (http://www.gnu.org/prep/standards_toc.html)

지나치게 긴 주석을 달아야만 이해할 수 있는 코드는 잘못 설계된 코드라는 말이 가슴에 와 닿더군요

그리고, 프로젝트를 진행하다 보면 세세한 주석은 가독성을 떨어뜨리는 것도 문제지만 소스 변경시 주석고치는 작업이 번거롭고 그런 핑계로 수정때 나중에 반영하지 뭐 하면서 몇개 빼먹다 보면 최악의 케이스인 틀린, 또는 부적절하거나 불필요한 주석이 여기저기 난무하게 되더군요. 코드를 간결, 명확하게 설계하고 주석은 필요한 만큼만 쓰고 수정을 항상 정확하게 반영하는게 장기적으로는 오히려 더 중요하다고 생각합니다.

개인적으로는 주석에 변경 history를 남기는 습관이 있고 버젼컨트롤툴을 쓰면서 변경이 생기는 버젼때만 버젼과 함께 주석에 기록을 남겨놓으면 나중에 변수별 function 별 history를 손쉽게 추적할 수 있어서 좋더군요.

redbaron의 이미지

프로그래밍의 모든것(The Practice of Programming), KernighanBrian 그리고 PikeRob, 1999, ISBN 0-201-61586-X, Addison-Wesley.
번역본이 있습니다.
찾아보시길...
그럼.이만..
꾸벅.

익명 사용자의 이미지

위의 글에 보니 님은 그 한글로 된 문서가 어디에 있는지 아시겠군요...
그렇다면 그 문서가 어디에 있는지 설명을 해주셨으면 더 좋았을 텐데요...
어떤 사람이 질문을 했는데... 어 그건 찾아보면 다 있어..
라고 말하면 짜증나겠지요...
위에서 님이 말한 문서를 찾기 위해서, 전 또 얼마의 시간을 보내야겠지요...
다음부터는 그러지 맙시다.
그럼

익명 사용자의 이미지

저건 책인거 같은데...
제가 샀거든요

보통 저런건 웹에 없어요...이미 출판된 책은...

익명 사용자의 이미지

저건 책인거 같은데...
제가 샀거든요

보통 저런건 웹에 없어요...이미 출판된 책은...

익명 사용자의 이미지

저는 아무래도 초보의 입장으로서, 나중에 알아보기 좋도록 아예 변수 이름 같은 것 자체를 뜻을 포함하게 짓는 편입니다. 주석은 단락 위에다가 쓰고요. 되도록 자세하게요....

예를 들면 뭐, if의 위의 줄, for의 위의 줄, 혹은 변수들 선언하는 윗줄에다가. 개인적인 버릇이죠, 뭐....^^

익명 사용자의 이미지

저는 아직 프로그래머라고 하기엔 우스운 수련생이지만...

제가 주석을 다는 스타일은 전적으로 Practical 시리즈에 영향을 받았습니다.

에... 대충 보면,
코드 맨 우에는...

/********************
* *
********************/

이런식으로 박스를 만들어서 잡다한 정보를 넣어두고요, 함수위에 는,

/*
*
*/

이런식으로 주석을 답니다.

그리고 어떤 구획에 주석을 다는 경우 그 구획은 일단 한줄 띄어서 구분하고 구획의 맨 위에 주석을 답니다.
(덕분에 제 소스는 빈줄이 아주 많습니다. :-) )

그 다음 한 문장에서는 문장 끝에 답니다.
(Emacs에서 M-; 쓰면 직빵이거던요.)

저는 왕초보라 일단은 주석은 최대한 많이 달자! 라는 주의로 플밍하고 있습니다.
물론 쓸데없이 많은 주석또한 가독성을 떨어뜨리지만 주석이 없는 코드에 비한다면야...

이상입니다.
(- -)(_ _)

익명 사용자의 이미지

>>ㅑ~ 주석이 찌그러지는군요.
다시, 다시....

/**************************
.*........................*
.*........................*
.**************************/

/*
.*
.*
.*/

이겁니다. ㅡㅡ;;;

익명 사용자의 이미지

쿠쿠 내는 폰트가 이상해서인자는 몰라도 요기 주석도 찌그러져보인다 아입니꺼^^

익명 사용자의 이미지

저는 if for switch while 등을 마감할 때 /* end of ... */ 를 씁니다. 파일 마감할 때도 역시 /* end of xxx.c */ 라고 하고요. 소스 수정 로그를 설명하는 일도 해야하고...
i++ 에 커맨트 다는 일은 되도록 피해야 겠지만, 바로 그 윗 문장에 커맨트를 달면 그 아래쪽 문장에 그 윗 문장 하는 일에 귀속되는 것으로 보이는 경향이 있어, 불가피하게 주석으로 구획을 나누는 일도 있는 것 같네요. 저는 적어도 초보는 아니라고 생각되는데, 주석은 많이 다는 편입니다. 제 경험상 해를 거듭한 뒤 다시 들여다 보면 자기 소스 자기가 분석하는 어처구니 없는 일이 벌어지더군요. 주석을 영어로 달면, 영작문 연습에 많은 도움이 되어 일석 이조를 거둘 수 있는 것 같습니다.

가끔 텍스트 그림을 그리는 것도 필요한 것 같고, 어쨌는 당시 갖게된 구현 이념을 명백하고 많이 적어 놓는 것이 좋은 것 같습니다.

익명 사용자의 이미지

많이들 쓰는 방법중에...

/////////////////////////////////////
//
// function Description
//
void function(
int Var1, // Variable Description
int Var2) // Variable Description
{
...
}

익명 사용자의 이미지

전 이렇게 해요^^
///////////////////////////////////
// //
// function //
// //
///////////////////////////////////

///////////////////////////////////
// member function //
///////////////////////////////////

익명 사용자의 이미지

전 이렇게 해요 --; (들키면 클남 --;)

// / / / / /
// / / / / // /
// / / / / /
// / It's Rainy Day... / /
// / / / /
// /

익명 사용자의 이미지

이런...깨진다... --;
비오는 것같은 효과를 내는 건데... --;

익명 사용자의 이미지

C#에서는 /// 로 시작하는 주석을 document로 파싱해 주죠.(흑. 국어가 딸려서)

저도 자바와 같은 표준화된 문서화주석(Documentation comment)을 좋와합니다. 나중에 쭈욱 뽑아서 내가 뭐 짰는가 알수도 있고.

최근 들어 다른 소스를 분석해서 추가, 수정하는 일을 맏았는데, 정말 주석의 필요성이 절실하더군요. 워낙에 주석에 인색한 소스라서 이름만으로 예상하고 한줄씩 따라가고.. 주석이 좀더 있었다면 더욱 작업 시간을 줄이고 다른곳에 시간을 투자할수 있을꺼라는 생각이 듭니다.

코딩의 필요성은..

아무리 코딩의 신이라도 주석은 꼭 필요합니다. 천재의 생각을 알고 싶은 많은 사람들이 있으니까요...
범인이라면, 더욱 필요합니다. 한달뒤에 그 코드 볼일이 있기에..

대강 이런 생각으로, 주석을 다는데, 요즘 황당한건, 한글이 지원되지 않는 환경에서의 주석달기 입니다. T_T (리눅스용 J빌더 등등..--;)차라리 영어권에서 태어 났으면 하는 생각도 듭니다. 생각을 해도 표현력이 부족하니 원..

클래스에서는 쓰임새, 사용 라이브러리, 연계 클래스
(association관계정도는 서술을.. T_T 상속은 코드상에 표현이 되니..)

함수내에서는 필요성과 알고리즘 서술 정도면 적당한거 같구..

특히! 중요한건..
"""자신이 프로그램에 꽁수를 부려놨을때...""" (<-이거에 한이 맺혀서 - -;)
코드에 대한 서술이 꼭 있어야 할꺼 같습니다.

다른 사람이 정말 황당합니다. (여기에 다른 사람은 범인의 6개월뒤의 나도 포함됩니다. --;)

PS. 진짜 잡담이군요.. --; 너무 당연한 말만 늘어 놓아서..

익명 사용자의 이미지

C/C++로 한정하라고 하셨지만 ^^
Java의 경우는 JavaDoc이라는 Documentation tool이 있어서 그 형식에 맞추어서 comment를 달면 자동으로 API 문서를 만들어줄 때 내용에 포함이 되더군요~

method나 class 앞에
/**
* method or class의 간략한 설명 .(마침표!)
* method or class의 자세한 설명
*
* @param 파라미터명 설명
* @return return값 설명
* @see 참고할 method or class
*/

형식이 요런식으로 되어있는데, 꽤 괜찮은 방법인 것 같더라구요~
자기만의 스타일도 괜찮겠지만 많은 사람들이 쓰는 방법을 따른다면 다른 사람들이 알아보기에도 쉬울테니 말이죠

익명 사용자의 이미지

흠 눈 감아도 코딩하는 고수들은 함수 하나에 모든 내용을 함축 한다고는 합니다

하지만 초보의 경우는 사정없이 주석을 달아서 나중에 볼때 편하게끔 하라고 하더군요 (-- );; 사정없이 달아야지

byteme_의 이미지

전 함수 시작부분과 global variable 선언에만 주로 달죠.
아, 그리고 항상 /* 커멘트를... 예전부터 쓰던 버릇이라서..

comment없는 코드도 보기 힘들지만,
comment가 쓸데없이 많은 코드는 더욱 보기 짜증나죠.

몇몇 책에서 불필요한 커멘트의 예를 들면서 항상 나오는 그거 있죠?
-----------------------
i++; // increment i by one
-----------------------

지금 제가 분석하는 코드에 누군가가 이런 짓을 해놨더군요..
(그것도 무진장 많은 곳에서.. 흐흑. -_- )

익명 사용자의 이미지

근데... i가 무엇인가요?
도대체 어떤 역할을 맡길려구... 카운터로 사용하셨나요?
그 "어떤 역할"이 중요한데...
피터노턴(피터노턴의 C/C++)을 제외한 모든 분들이 그 역할에 대해서는 설명하지 않더군요.

익명 사용자의 이미지

저같은 경우 문맥으로 봤을때 중요한곳에

//을 써서 답니다. 그리고 함수의 시작부분에 함수의 용도

precondition과 postcondition, 그리고 parameter에

in, out, inout을 답니다.

그리고 각 변수의 용도는 변수명으로 주석을 대체 하지요.

댓글 달기

Filtered HTML

  • 텍스트에 BBCode 태그를 사용할 수 있습니다. URL은 자동으로 링크 됩니다.
  • 사용할 수 있는 HTML 태그: <p><div><span><br><a><em><strong><del><ins><b><i><u><s><pre><code><cite><blockquote><ul><ol><li><dl><dt><dd><table><tr><td><th><thead><tbody><h1><h2><h3><h4><h5><h6><img><embed><object><param><hr>
  • 다음 태그를 이용하여 소스 코드 구문 강조를 할 수 있습니다: <code>, <blockcode>, <apache>, <applescript>, <autoconf>, <awk>, <bash>, <c>, <cpp>, <css>, <diff>, <drupal5>, <drupal6>, <gdb>, <html>, <html5>, <java>, <javascript>, <ldif>, <lua>, <make>, <mysql>, <perl>, <perl6>, <php>, <pgsql>, <proftpd>, <python>, <reg>, <spec>, <ruby>. 지원하는 태그 형식: <foo>, [foo].
  • web 주소와/이메일 주소를 클릭할 수 있는 링크로 자동으로 바꿉니다.

BBCode

  • 텍스트에 BBCode 태그를 사용할 수 있습니다. URL은 자동으로 링크 됩니다.
  • 다음 태그를 이용하여 소스 코드 구문 강조를 할 수 있습니다: <code>, <blockcode>, <apache>, <applescript>, <autoconf>, <awk>, <bash>, <c>, <cpp>, <css>, <diff>, <drupal5>, <drupal6>, <gdb>, <html>, <html5>, <java>, <javascript>, <ldif>, <lua>, <make>, <mysql>, <perl>, <perl6>, <php>, <pgsql>, <proftpd>, <python>, <reg>, <spec>, <ruby>. 지원하는 태그 형식: <foo>, [foo].
  • 사용할 수 있는 HTML 태그: <p><div><span><br><a><em><strong><del><ins><b><i><u><s><pre><code><cite><blockquote><ul><ol><li><dl><dt><dd><table><tr><td><th><thead><tbody><h1><h2><h3><h4><h5><h6><img><embed><object><param>
  • web 주소와/이메일 주소를 클릭할 수 있는 링크로 자동으로 바꿉니다.

Textile

  • 다음 태그를 이용하여 소스 코드 구문 강조를 할 수 있습니다: <code>, <blockcode>, <apache>, <applescript>, <autoconf>, <awk>, <bash>, <c>, <cpp>, <css>, <diff>, <drupal5>, <drupal6>, <gdb>, <html>, <html5>, <java>, <javascript>, <ldif>, <lua>, <make>, <mysql>, <perl>, <perl6>, <php>, <pgsql>, <proftpd>, <python>, <reg>, <spec>, <ruby>. 지원하는 태그 형식: <foo>, [foo].
  • You can use Textile markup to format text.
  • 사용할 수 있는 HTML 태그: <p><div><span><br><a><em><strong><del><ins><b><i><u><s><pre><code><cite><blockquote><ul><ol><li><dl><dt><dd><table><tr><td><th><thead><tbody><h1><h2><h3><h4><h5><h6><img><embed><object><param><hr>

Markdown

  • 다음 태그를 이용하여 소스 코드 구문 강조를 할 수 있습니다: <code>, <blockcode>, <apache>, <applescript>, <autoconf>, <awk>, <bash>, <c>, <cpp>, <css>, <diff>, <drupal5>, <drupal6>, <gdb>, <html>, <html5>, <java>, <javascript>, <ldif>, <lua>, <make>, <mysql>, <perl>, <perl6>, <php>, <pgsql>, <proftpd>, <python>, <reg>, <spec>, <ruby>. 지원하는 태그 형식: <foo>, [foo].
  • Quick Tips:
    • Two or more spaces at a line's end = Line break
    • Double returns = Paragraph
    • *Single asterisks* or _single underscores_ = Emphasis
    • **Double** or __double__ = Strong
    • This is [a link](http://the.link.example.com "The optional title text")
    For complete details on the Markdown syntax, see the Markdown documentation and Markdown Extra documentation for tables, footnotes, and more.
  • web 주소와/이메일 주소를 클릭할 수 있는 링크로 자동으로 바꿉니다.
  • 사용할 수 있는 HTML 태그: <p><div><span><br><a><em><strong><del><ins><b><i><u><s><pre><code><cite><blockquote><ul><ol><li><dl><dt><dd><table><tr><td><th><thead><tbody><h1><h2><h3><h4><h5><h6><img><embed><object><param><hr>

Plain text

  • HTML 태그를 사용할 수 없습니다.
  • web 주소와/이메일 주소를 클릭할 수 있는 링크로 자동으로 바꿉니다.
  • 줄과 단락은 자동으로 분리됩니다.
댓글 첨부 파일
이 댓글에 이미지나 파일을 업로드 합니다.
파일 크기는 8 MB보다 작아야 합니다.
허용할 파일 형식: txt pdf doc xls gif jpg jpeg mp3 png rar zip.
CAPTCHA
이것은 자동으로 스팸을 올리는 것을 막기 위해서 제공됩니다.