주석의 정의와 종류

※ 이클립스 기반 주석이다. (java, javascript, xml)

프로그래밍에 있어서 주석은 매우 중요한 부분이기 때문에 주석에 대해 정리해보았다.

주석의 정의

내용을 이해하기 쉽게 메모를 하는 것

프로그래밍 소스를 이해하기 쉽게 메모를 하는 것

특정 소스를 비활성화 하는 것 ("주석처리 한다" 라고 이야기한다)

 

주석을 사용해야 하는 이유

1. 소스에 대한 메모 

내가 개발한 소스를 함께 개발하는 팀원, 유지보수팀, 미래의 자신 등이 소스를 볼 때
이해하기 쉽게 도와주는 용도이다.

 

내가 상대방의 소스를 받아서 분석을 해야할 때 각 함수들이 어떠한 함수인지 알고 분석을 하면

분석할 때 좀 더 수월하지 않을까? 

내가 개발한 소스라고 해도 시간이 지나서 다시 본다면 이해가 안되는 함수들이 많은 것을 경험할 것이다. 

그럴때 도움을 주는 메모가 주석이다. 

 

주석을 자세하게 적기 보다는 합계, 평균 과 같이 간단하면서도 어떠한 함수인지 바로 알 수 있게 기록해주는 것이 중요하다. 또한 개발 소스가 많으면 많을 수록 주석도 많이 작성해주는게 좋다.

(최소한 소스의 최종목적이라도 기록해주자)

 

2. 소스 비활성화

특정 소스를 비활성화 시킬 때도 사용한다.

개발하는 과정에서 소스를 조금씩 변경해보면서 다양한 방법으로 테스트를 하게된다.

다양한 방법을 시도했음에도 결과가 원하는 대로 나오지 않으면 원본 소스로 돌려야 하는데

이때 Ctrl+z로 돌아가는건 한계가 있다. 

그렇기 때문에 이 때 원본 소스 주석으로 남겨놓고 복사해서 테스트를 하는게 좋다.

실행을 막고 싶은 소스가 있을 때도 주석처리를 하게 된다.

 

주석의 종류

< JAVA, JAVASCRIPT >

1. // 주석 내용 - 한줄 주석 (가장 많이 사용되는 주석)

   - 사용방법 : Ctrl + / (활성화, 비활성화 단축키 동일)

   - 주로 한 줄의 소스를 비활성화 할 때 많이 사용된다

   - 또한 간단한 설명을 기록할 때 사용 되기도 한다 (// 합계 함수)

2. /* 주석 내용 */ - 블록 주석

   - 사용방법 : /* + Enter

   - 여러 줄의 소스를 한번에 비활성화 할 때 사용할 수 있다

   - 소스에 대한 설명이 길 경우 사용하면 좋다

3. /** 주석 내용 */ - 문서 주석

   - 사용방법 : /** */

   - 자바 문서를 만들 때 사용한다

   - 이는 xml에서도 사용되는 주석인데 xml에서는 더욱 유용하게 사용할 수 있다

   - 사용할 수 있는 예약어가 있다

< 예약어 >

@author 개발자 
@exception 예외
@param 파라미터
@return 반환 값
@see 
@serial 
@since 
@throws 
@version 버전

< xml >

1. <!-- --> 

   - 사용방법 : <!-- 주석 내용 -->

   - 소스를 비활성화할 때 사용된다

   - 하이픈(-)의 개수는 상관 없으나 처음과 끝이 아닌 경우 두 개 이상 연달아 사용하면 오류가 난다

<!----- 이것은 -- 주석입니다. ---->  오류
<!----- 이것은 - - 주석입니다. ----> 정상인식

 

2. /** */ - 문서주석

   - 사용방법 : /** 주석 내용 */

   - 쿼리에 대한 설명을 기록할 때 사용하면 유용하다

   - <select>태그 안에 /** */로 기록을 하면 쿼리 로그에 해당 주석이 같이 출력이 되기 때문에

     쿼리를 검색하기도 편하고 쿼리의 목적을 알기도 수월하다.

   - 문서주석 후 출력 시 아래와 같이 출력된다

<select id="selectCompanyList" resultType="List">      
    /** 회사 조회 리스트 */
     SELECT 
        COMPANY_CD
        , COMPANY_NM
     FROM COMPANY
        ORDER BY COMPANY_CD     
</select>

========================= console ==============================

/** 회사 조회 리스트 */
SELECT 
   COMPANY_CD
   , COMPANY_NM
FROM COMPANY
   ORDER BY COMPANY_CD

 

개발에 있어서 주석은 나에게도, 상대방에게도 매우 중요한 것이다.

그러니 이 글을 본 순간부터라도 짧고 간단한 내용이여도 주석으로 메모를 하는 습관을 가지도록 하자.