[델파이] 바람직한 주석(Comment)달기

[델파이] 바람직한 주석(Comment)달기

개발 단계에서 구현 목적이나 방법등이 소스코드를 살펴보면 알 수 있지만 다른 개발자가 코딩한 소스를 해석하기에는 여간 쉬운일이 아니다. 현 시점에서는 내가 이 프로그램을 지속적으로 관리할 것 같지만 시간이 지나면 누군가 이 프로그램을 유지보수 하고 있을 확률이 대단히 높다. 이때 후임 개발자가 소스 분석시 전임 개발자의 개발의도를 정확히 파악하기 쉽지 않음에 따라 전임 개발자를 평가 절하시킬 수도 있다..

1. 주석을 달아야 하는 이유

1) 대부분의 개발자는 문서화 작업을 너무 싫어 한다(?)

2) 코딩 후 시간이 지나면 나도 잊어버린다.

3) 내가 개발한 소스 코드를 남이 수정해야 할 확율이 대단히 높다.

4) 유지보수성을 증대 시킨다.

5) 프로그램의 완성도를 높인다(?)

6) 추가 문서작업에 대한 부담을 줄여준다.

2. 주석 처리의 종류

1) LINE Comments : '//' 심볼을 이용하여 심볼 이후 해당 라인만 주석으로 처리된다

2) BLOCK Comments : "{  }" 또는 "(* *)"를 이용하여 브라켓 안쪽의 모든 문구가 주석으로 처리된다.

3. 주석처리 권고

1) 델파이 PASCAL 언어에서는 동일한 심볼을 이용한 중첩 주석처리를 지원하지 않는다

2) 모든 유닛의 시작 부분에 BLOCK Comments 심볼을 이용하여 해당 유닛에 대한 용도 및 작성자, 작성일 및 기타 해당 유닛을 이해하는데 도움이 되는 설명 문구를 기록한다. 또한 수정 이력(History)를 명시하여 유닛이 수정될 때마다 수정자 및 수정 사항을 기록하도록 유도한다.

unit uCommonLib;
{** DelphiXE 이상의 버전에서 각종 유용한 함수들의 구현
 * 관련 함수
 *   1) XML 노드 다루기
 *   2) 프로세스 강제 종료시키기
 *   3) HTTP프로토콜을 이용한 파일 업로드/다운로드
 *
 * 작성자 : 홍길동
 * 작성일 : 2015-02-03
 * History
 *    2015.02.05, 홍길동 : 파일업로드 속도 향상(Winnet Suite 이용)
 * }

interface

3) 클래스 작성시 클래스 선언부 위에 해당 클래스의 역할 및 기능에 대해 명시한다.

4) Function / Procedure 선언부에 역할 및 목적, 각 파라미터에 대한 정의, 리턴 값에 대한 정의 등을 기술한다.

5) Function / Procedure 에 대한 주석은 향후 JavaDoc 을 통해 향후 HTML Reference문서를 만들 수 있도록 JAVA 주석처리와 유사하게 작성한다.

  사용예)

{** 관심뉴스의 기사 목록을 요청합니다.
  @param nPage 페이지 번호
  @param nKNo 관심그룹의 고유 번호
  @param strSCT 검색 대상 매체
  @param dtStart 검색 시작 날짜
  @param dtEnd 검색 종료 날짜
  @param nPageSize 페이지당 기사 수
  @return 처리성공유무
  *}
function TRequestThread.ReqFavoriteList(const strKType: string = ''; nKNo: integer = 0;
        const strGGroup: string = ''; const strSCT: string = ''; dtStart: TDateTime = 0;
        dtEnd: TDateTime = 0; nHasSummary: integer = 0; nPage:integer = 1; nPageSize: integer = 30) : Boolean;
var
  strPostData: string;
  chkSct : string;
//...

6) Pascal Code 자체만으로 명백한 주석은 피한다

  예) i := i + 1; // i변수에 1을 더한다

7) BLOCK Comments를 사용할 경우에는 가급적 "{ }"를 사용한다.

8) 불명확하거나 잘못된 주석은 없는 것보다 못하므로 피한다.

9) "(* *)" BLOCK Comments 심볼은 개발 이후 지워도 되는 테스트용도 또는 임시적으로 쓰는 주석으로 제한한다.

10) 주석이 단일라인일 경우는 "//" 심볼 주석을 이용한다.

11) 불명확하거나, 나중에 보완해야 하거나, 꼼수등 비정상적으로 처리된 코드는 반드시 주석을 달아서 의도를 명시한다.

12) 모든 주석은 왼쪽으로 정렬한다.

13) 소스코드가 수정 되었다면 해당 소스코드에 대한 주석이 있을 경우 변경된 사항을 반드시 주석에도 반영해 주어야 한다.

14) 소스를 설명할 때에는 가급적 해당소스가 무엇을 하는지 위주로 작성하도록 한다(목적성 기반). 만일 어떻게 하는지에 대해서를 기술 한다면 소스가 변경될 때마다 해당 변경된 방법을 함께 기술해주어야 하기 때문에 유지보수성이 떨어진다.

15) 주의 할 것은 소스코드가 변경될 시점에 바로 주석도 함께 변경해 주어야 불일치를 막는 가장 현명한 방법임(나중에.... 건망증)

4. 결언

  개발자는 문서 작업을 꺼린다.. 이건 우리 개발자들에게 통념으로 이해되고 있습니다. 그렇지만 내가 만든 코드도 1주일, 한달이상 지나면 망각이 늪에 빠지게 되어 다시 구현 의도부터 되짚어 봐야하는 우를 범하게 되지요. 이때 그당시 생각했던 것을 쉽게 복기 할 수 있다면 개발 생산성을 확실히 줄일 수 있습니다.

  개발소스 코드를 예술이라고 생각한다면 주석은 내 예술 작품을 더 우아하게 만드는 데코레이션 작업이 되겠지요... 그리고 나중에 후임 개발자에게 욕먹을 여지를 남겨두지 않으려면 주석은 반드시, 정성들여서 기록 하도록 합니다. 

최소한 별도 문서작성 대신에 소스코드 주석만이라도 다는 개발자의 의무를 충실히 이행 하는 좋은 개발자가 되도록 하세요...