From ["ProjectZephyrus/ClientJourney"]

''주석이 없는 코드라서 그런지 해석하는 데 애먹었다''

그렇다면 자신이 그 코드를 해석하면서 얻은 지식을 그 코드에 적용했더라면(좀 더 의미있는 변수이름, 메써드이름 사용, 코드 일부분을 의미있는 이름의 메써드로 추출 등) 어땠을까요? --JuNe
   아..["Refactoring"] 하라는 거군요.. 사실 설계 자체에서도 빠진 상태라 전체 구조 이해하는데 가장 크게 애를 먹었습니다. 아무튼 진짜 이해한 후에 코드를 수정해 놓는 것도 좋은 방법인건 분명하다고 생각합니다. ^^; --창섭

처음에 Javadoc 을 쓸까 하다가 계속 주석이 코드에 아른 거려서 방해가 되었던 관계로; (["IntelliJ"] 3.0 이후부턴 Source Folding 이 지원하기 때문에 Javadoc을 닫을 수 있지만) 주석을 안쓰고 프로그래밍을 한게 화근인가 보군. 설계 시기를 따로 뺀 적은 없지만, Pair 할 때마다 매번 Class Diagram 을 그리고 설명했던 것으로 기억하는데, 그래도 전체구조가 이해가 가지 않았다면 내 잘못이 크지. 다음부터는 상민이처럼 위키에 Class Diagram 업데이트된 것 올리고, Javadoc 만들어서 generation 한 것 올리도록 노력을 해야 겠군. 

요새들어서 주석을 잘 안쓰고 코드를 알아보기 쉽게 쓰려고 노력하긴 하는데, 아직 수련이 부족해서인지 코드는 코드대로 어렵고 주석은 주석대로 없나 보다. 흐흐; 

약간 변명이라면, 개인적 경험에서는 주석이 달린 코드는 주석에 시선이 먼저가고, 주석이 없는 코드에는 함수 프로토타입에 시선이 먼저간다라는 것. 하지만, 의도가 전해지지 않았다면 역시 뭐 무의미한것이겠지. --석천

내가 가지는 주석의 관점은 지하철에서도 언급한 내용 거의 그대로지만, 내게 있어 주석의 주된 용도는 과거의 자신과 대화를 하면서 집중도 유지, 진행도 체크하기 위해서 이고, 기타 이유는 일반적인 이유인 타인에 대한 정보 전달이다. 전자는 command.Command.execute()이나 상규와 함께 달은 information.InfoManager.writeXXX()위의 주석들이고,후자가 주로 쓰인 용도는 각 class 상단과 package 기술해 놓은 주석이다. 그외에 class diagram은 원래 아나로그로 그린것도 있지만, 설명하면서 그린건 절대로 타인의 머리속에 통째로 저장이 남지 않는다는 전제로, (왜냐면 내가 그러니까.) 타인의 열람을 위해 class diagram의 디지털화를 시켰다. 하는 김에 그런데 확실히 설명할때 JavaDoc뽑아서 그거가지고 설명하는게 편하긴 편하더라. --["상민"]

자바 IDE들이 Source Folding 이 지원하거나 comment 와 관련한 기능을 지원한다면 해결될듯. JavaDoc 은 API군이나 Framework Library의 경우 MSDN의 역할을 해주니까. --석천

자네의 경우는 주석이 자네의 생각과정이고, 그 다음은 코드를 읽는 사람의 관점인 건데, 프로그램을 이해하기 위해서 그 사람은 어떤 과정을 거칠까? 경험이 있는 사람이야 무엇을 해야 할 지 아니까 abstract 한 클래스 이름이나 메소드들 이름만 봐도 잘 이해를 하지만, 나는 다른 사람들이 실제 코드 구현부분도 읽기를 바랬거든. (소켓에서 Read 부분 관련 블럭킹 방지를 위한 스레드의 이용방법을 모르고, Swing tree 이용법 모르는 사람에겐 더더욱. 해당 부분에 대해선 Pair 중 설명을 하긴 했으니) 

그리고 개인적으론 Server 쪽 이해하기로는 Class Diagram 이 JavaDoc 보는것보다 더 편했음. 그거 본 다음 소스를 보는 방법으로 (완벽하게 이해하진 않았지만.). 이건 내가 UML 에 더 익숙해서가 아닐까 함. 그리고 Java Source 가 비교적 깨끗하기에 이해하기 편하다는 점도 있겠고. (그래 소스 작성한 사람 칭찬해줄께;) --석천
 좌절이다. 일단 자네 의견에 동의 정도가 아니라 같은 의도의 말이었다. 위의 자네 말에 대한 내가 의미를 불확실하게 전달한거 같아서 세단락 정도 쓴거 같은데.. 휴 일단 다시 짧게 줄이자면, "프로그래머의 낙서의 표준"인 UML과 {{{~cpp JavaDoc}}}의 출발은 아예 다르다. 자네가 바란건 디자인 단위로 프로그래밍을 이해하길 원한거 같은데, 그것을 {{{~cpp JavaDoc}}}에서 말해주는건 불가능하다고 생각한다. Sun에서 msdn에 대응하기 위해(?) {{{~cpp JavaDoc}}}이 태어난것 같은데 말이다. [[BR]]
 하지만, "확실히 설명할때 {{{~cpp JavaDoc}}}뽑아서 그거가지고 설명하는게 편하긴 편하더라."라고 한말 풀어쓰는 건데, 만약 디자인 이해 후에 코드의 이해라면 {{{~cpp JavaDoc}}} 없고 소스만으로 이해는 너무 어렵다.(최소한 나에게는 그랬다.) 일단 코드 분석시 {{{~cpp JavaDoc}}}이 나올 정도라면, "긴장 완화"의 효과로 먹고 들어 간다. 그리고 우리가 코드를 읽는 시점은 jdk를 쓸때 {{{~cpp JavaDoc}}}을 보지 소스를 보지는 않는 것처럼, 해당 메소드가 library처럼 느껴지지 않을까? 그것이 메소드의 이름이나 필드의 이름만으로 완벽한 표현은 불가능하다고 생각한다. 완벽히 표현했다면 너무나 심한 세분화가 아닐까? 전에 정말 난해한 소스를 분석한 적이 있다. 그때도 가끔 보이는 실낱같은 주석들이 너무나 도움이 된것이 기억난다. 우리가 제출한 Report를 대학원 생들이 분석할때 역시 마찬가지 일것이다. 이건 궁극의 Refactoring문제가 아니다. 프로그래밍 언어가 그 셰익스피어 언어와 같았으면 하기도 하는 생각을 해본다. 생각의 언어를 프로그래밍 언어 대입할수만 있다면야.. --["상민"]

난해한 코드일수록 주석이 필요한 것일것이고 (또는 그 반대로 쉽게 알아볼 수 있도록 짤 방법을 강구해야 한다면 억지쓰는 것이려나.) 개인적으로 읽어본 가장 긴 낯선 코드가 3000~4000 라인을 못넘어 본 관계로 아직은 '정리' 단계로만 끝날 것 같다. CVS 의 history 가 코드 진화과정을 따라가는데 도움을 줄것이라고 생각했지만, 아직은 먼 이야기일듯. 

내가 Comment 와 JavaDoc 둘을 비슷한 대상으로 두고 쓴게 잘못인듯 하다. 두개는 좀 구분할 필요가 있을 것 같다는 생각이 들어서다. 내부 코드 알고리즘 진행을 설명하기 위해서는 다는 주석을 comment로, 해당 구성 클래스들의 interface를 서술하는것을 JavaDoc으로 구분하려나. 이 경우라면 JavaDoc 과 Class Diagram 이 거의 비슷한 역할을 하겠지. (Class Diagram 이 그냥 Conceptual Model 정도라면 또 이야기가 달라지겠지만) 

     그리고, JDK 와 Application 의 소스는 그 성격이 다르다고 생각해서. JDK 의 소스 분석이란 JDK의 클래스들을 읽고 그 interface를 적극적으로 이용하기 위해 하는 것이기에 JavaDoc 의 위력은 절대적이다. 하지만, Application 의 소스 분석이라 한다면 실질적인 implementation 을 볼것이라 생각하거든. 어떤 것이 'Information' 이냐에 대해서 바라보는 관점의 차이가 있겠지. 해당 메소드가 library처럼 느껴질때는 해당 코드가 일종의 아키텍쳐적인 부분이 될 때가 아닐까. 즉, Server/Client 에서의 Socket Connection 부분이라던지, DB 에서의 DB Connection 을 얻어오는 부분은 다른 코드들이 쌓아 올라가는게 기반이 되는 부분이니까. Application 영역이 되는 부분과 library 영역이 되는 부분이 구분되려면 또 쉽진 않겠지만.

이번기회에 comment, document, source code 에 대해서 제대로 생각해볼 수 있을듯 (프로그램을 어떻게 분석할 것인가 라던지 Reverse Engineering Tool들을 이용하는 방법을 궁리한다던지 등등) 그리고 후배들과의 코드에 대한 대화는 익숙한 comment 로 대화하는게 낫겠다. DesignPatterns 가 한서도 나온다고 하며 또하나의 기술장벽이 내려간다고 하더라도, 접해보지 않은 사람에겐 또하나의 외국어일것이니. 그리고 영어가 모국어가 아닌 이상. 뭐. (암튼 오늘 내일 되는대로 Documentation 마저 남기겠음. 글쓰는 도중 치열하게 Documentation을 진행하지도 않은 사람이 말만 앞섰다란 생각이 그치질 않는지라. 물론 작업중 Doc 이 아닌 작업 후 Doc 라는 점에서 점수 깎인다는 점은 인지중;) --석천

DeleteMe)위에 좌절인 이유를 안써놨는데, 상세히 각 종류별로 생각을 적어 놓았는데, commit시에 충돌이 나서 먹어 버렸어. 하..하..하 ...  암튼 이번에 프로그래밍을 하면서 생각한 컨셉들을 서로 설명하면서 같이 말해야 겠군. [[BR]]
그리고 계속 이야기 하다보니 주석(comment)과 {{{~cpp JavaDoc}}}을 나누어 설명하는 것이 올바른 생각인듯 하다. 그런 관점이라면 이번 코딩의 컨셉이 녹색글자 최소주의로 나갔다고 볼수 있다. 머리속으로는 특별히 둘을 나누지 않고 있었는데, 코딩 습관에서는 완전히 나누고 있었던거 같다. 녹색 글자를 쓰지 않을려고 발악(?)을 했으니.. 그래도 보이는 녹색 글자들 보면 죄의식이 이것이 object world에서 말하는 "프로그래머의 죄의식"에 해당하는 것이 아닐까. --["상민"]
   ''DeleteMe) 부연설명 : 녹색글자는 ["Eclipse"] 에서 내부 주석에 대당. ["IntelliJ"] 는 일반적으로 회색. ["Vi"] 에서의 Java Syntax 에선 파란색.''

----
'''재미있는 주석'''

주석이 실행될 수 있는 코드가 아니기 때문에, 반드시 코드가 주석대로 수행된다고 볼 수는 없지만 없는것 보다는 낳은 경우도 많다. 코드 자체는 언어의 subset 이기 때문에 아무리 ''코드가 이야기한다(code tells)''라 할지라도 우리가 쓰는 언어의 이해도에 미치기가 어렵다. 이는 마치, 어떤 일을 함에 있어서 메뉴얼이 존재함에도 불구하고 경험자에게 이야기를 듣고 메뉴얼을 볼 경우, 그 이해가 쉽고 빠르게 되는것과 비슷하다. 

프로그램에 있어 주석이 하는 순기능을 하나 더 찾아볼 수 있다. ''메마른 코드속에서 사람의 숨결을 느끼게 해준다.'' 유머가 없는 세상을 생각해보라. 얼마나 끔찍한가.

예를 들어 다음의 코드를 살펴보자(회사에서 누군가 작성한 코드)

 {{{~cpp 
...
		// 자식들 다 쥑이고...
		CSmilNode* pChildNode = m_pFirstChild;
		while(pChildNode)
		{
			CSmilNode* pDelNode = pChildNode;
			pChildNode = pChildNode->m_pNext;
			pDelNode->deleteSafely(bRecursive);
			pDelNode = NULL;
		}

		// 형제의 연을 다 끊고...
		if(m_pPrev)
			m_pPrev->m_pNext = m_pNext;
		if(m_pNext)
			m_pNext->m_pPrev = m_pPrev;

		// 부모의 연도 끊은 다음...
		if(m_pParent  &&  m_pParent->m_pFirstChild == this)
			m_pParent->m_pFirstChild = m_pNext;

		// 자살한다.
		delete this;
...
}}}

또 다른 예도 있다.

 {{{~cpp 
...
// MODE_ADDBEFORE일 때는, newnode가 this의 자식인 brother의 바로 윗형으로 입양을 간다.
// MODE_ADDAFTER일 때는, newnode가 this의 자식인 brother의 바로 아래 동생으로 입양을 간다.
// 입양을 갈때, 자식들은 항상 데리고 다니지만, 부모나 형제와는 떨어지는 것을 원칙으로 한다.
// 새식구를 받을때, 먼저 부모 자식간의 관계를 정립한 다음, 형제간의 서열을 정립한다.
//
// Default Parameter
//	nMode = MODE_ADDBEFORE
//	brother = NULL
// Constraint
//	brother는 반드시 NULL이거나 this의 child node이어야 한다.
// 사용예
//	addChild(newnode, MODE_ADDAFTER, brother);		//newnode가 brother 바로 뒤에 삽입된다.
//	addChild(newnode, MODE_ADDBEFORE, brother);		//newnode가 brother 바로 앞에 삽입된다.
//	addChild(newnode, MODE_ADDAFTER);				//newnode가 first child로 삽입된다.
//	addChild(newnode, /*MODE_ADDBEFORE*/);			//newnode가 last child로 삽입된다.
//
CSmilNode* CSmilNode::addChild(CSmilNode* newnode, DCLADDMODE nMode, CSmilNode* brother)
//	this = 내(부모)
//	newnode = 자식(새놈)
//	brother = (this의 자식인)윗형
...
}}}

이선우는 이러한 코드를 보며 여느때와 같은 지루함을 느끼지 못했다. (모든 주석 없는 코드가 다 지루하다는 뜻은 아니다. 분명 예술적인 코드는 코드 자체로 신비롭다. 문제는 이런 코드를 자주 만나기 어렵다는데 있다.) 정말, 재미있지 않은가?

우리는 충분히 이성적이기에 주석 자체만을 보고 모든것을 믿으려고 할 만큼 어리석지는 않다. 주석을 먼저 거쳐간 사람의 숨길로 느끼고, 재미로 느낄 수 있게 되면 코드 리뷰가 항상 지루하지는 않을 것이다.

코드 자체로서 의미를 이야기할 수 있도록 이름을 잘 짓는 것은 분명 중요하지만, 그에 못지 않게 코드를 읽고 작성하는 주체가 사람임을 생각할때 주석은 이들을 위한 작은 배려라 할 수 있다.

--이선우
----
See Also Seminar:CommentOrNot , NoSmok:DonaldKnuth 's comment on programs as works of literature