델파이에서 바람직한 주석(Comment) 달기(유지보수를 위한 핵심 가이드)

소프트웨어 개발 과정에서 주석(comment)은 코드의 가독성을 높이고, 유지보수를 용이하게 만드는 중요한 요소입니다. 특히, 델파이(Delphi)와 같은 프로그래밍 언어를 사용할 때, 주석의 역할은 단순히 코드의 의도를 설명하는 것을 넘어, 후임 개발자나 본인이 나중에 코드를 다시 읽을 때 혼란을 줄이고 효율성을 높이는 데 크게 기여합니다. 본 글에서는 델파이에서 바람직한 주석을 다는 방법과 그 중요성에 대해 깊이 있게 탐구하겠습니다.

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

1.1 문서화의 필수성

대부분의 개발자는 문서화 작업을 귀찮아하며 피하고 싶어 하지만, 시간이 지남에 따라 자신의 코드조차도 잊어버리기 쉽습니다. 이 때문에 주석을 달아두지 않으면 나중에 코드를 다시 이해하는 데 큰 어려움을 겪게 됩니다. 주석은 코드의 문서화 작업을 대체할 수 있으며, 개발 생산성을 높이는 데 큰 역할을 합니다.

주요 포인트:

• 주석을 통해 코드의 의도와 구조를 명확히 설명
• 개발 후 시간이 지나도 코드를 쉽게 이해하고 수정 가능

1.2 코드 유지보수의 용이성

코딩 후 시간이 지나면 자신이 작성한 코드조차도 기억나지 않는 경우가 많습니다. 이때, 주석이 없으면 코드의 의도와 기능을 다시 이해하는 데 많은 시간이 소요됩니다. 주석을 달아두면, 자신뿐만 아니라 다른 개발자가 코드를 수정할 때에도 큰 도움이 됩니다.

유지보수성 증가:

• 다른 개발자가 코드를 쉽게 이해하고 수정 가능
• 코드의 완성도와 유지보수성을 높임

2. 주석 처리의 종류

2.1 라인(Line) 주석

라인 주석은 '//' 심볼을 사용하여 해당 라인만 주석으로 처리하는 방식입니다. 이 방식은 간단한 주석이나 단일 라인에 대한 설명을 추가할 때 유용합니다.

i := i + 1; // i 변수에 1을 더함

라인 주석의 장점은 코드의 흐름을 방해하지 않으면서도 해당 라인에 대한 명확한 설명을 제공한다는 점입니다.

2.2 블록(Block) 주석

블록 주석은 { } 또는 (* *) 심볼을 사용하여 여러 라인을 주석으로 처리하는 방식입니다. 이 방식은 함수나 클래스 전체에 대한 설명, 또는 코드 블록에 대한 상세한 설명을 작성할 때 유용합니다.

{**
 * 이 함수는 특정 파일을 서버로 업로드하는 기능을 수행합니다.
 * @param FileName 업로드할 파일의 이름
 * @return 성공 여부를 반환합니다.
 *}
function UploadFile(const FileName: string): Boolean;

2.3 중첩 주석 처리의 제한

델파이의 PASCAL 언어에서는 동일한 심볼을 이용한 중첩 주석 처리를 지원하지 않습니다. 이는 코드에 주석을 달 때 주의해야 할 중요한 점 중 하나입니다. 중첩 주석을 잘못 사용하면 코드가 예상치 못한 동작을 할 수 있기 때문에, 주석 처리 시에는 항상 주의를 기울여야 합니다.

 

3. 바람직한 주석 처리 권고사항

3.1 유닛(Unit) 시작 부분의 블록 주석

모든 유닛의 시작 부분에 블록 주석을 사용하여 해당 유닛의 용도 및 작성자, 작성일, 기타 유닛을 이해하는 데 도움이 되는 설명 문구를 기록하는 것이 좋습니다. 또한, 수정 이력(History)을 명시하여 유닛이 수정될 때마다 수정자 및 수정 사항을 기록하도록 유도합니다.

unit uCommonLib;

{**
 * 이 유닛은 다양한 유용한 함수들을 포함하고 있습니다.
 * 관련 함수:
 *   1) XML 노드 처리
 *   2) 프로세스 강제 종료
 *   3) HTTP 프로토콜을 이용한 파일 업로드/다운로드
 *
 * 작성자: 홍길동
 * 작성일: 2023-08-13
 * History:
 *   2023-08-15, 홍길동: 파일 업로드 속도 향상(Winnet Suite 사용)
 *}
interface

3.2 클래스 및 함수 주석

클래스나 함수 선언부 위에는 해당 클래스 또는 함수의 역할과 목적을 명시하는 주석을 추가하는 것이 좋습니다. 이 주석은 나중에 코드를 유지보수할 때 코드의 구조와 역할을 쉽게 파악할 수 있도록 도와줍니다.

{**
 * 관심 뉴스의 기사 목록을 요청합니다.
 * @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; nPageSize: Integer = 30): Boolean;

3.3 불명확하거나 잘못된 주석의 위험성

불명확하거나 잘못된 주석은 없는 것보다 더 나쁜 결과를 초래할 수 있습니다. 코드가 변경된 후에도 주석이 업데이트되지 않으면, 주석이 오히려 오해를 불러일으킬 수 있습니다. 따라서, 주석을 달 때에는 항상 정확하고 명확하게 작성해야 하며, 코드가 변경될 때 주석도 함께 업데이트해야 합니다.

 

3.4 주석 작성 시 피해야 할 점

• 명백한 코드에 대한 주석을 피하라: 주석이 코드와 동일한 내용을 반복한다면, 이는 불필요한 주석입니다.

i := i + 1; // i에 1을 더함

 

• 임시 또는 테스트용 주석의 제한적 사용: (* *) 블록 주석 심볼은 개발 이후 제거될 수 있는 테스트용 또는 임시 주석으로만 사용해야 합니다.
• 정확성과 일관성 유지: 주석은 항상 왼쪽으로 정렬하고, 수정된 소스 코드에 대한 주석도 반드시 업데이트해야 합니다.
• 목적성 기반 주석 작성: 소스 코드가 무엇을 하는지를 중심으로 주석을 작성하는 것이 바람직합니다. 어떻게 하는지를 설명하는 주석은 코드 변경 시마다 함께 업데이트해야 하기 때문에 유지보수성이 떨어질 수 있습니다.

4. 결론

소프트웨어 개발 과정에서 주석은 단순한 보조 도구가 아니라, 코드의 가독성 및 유지보수성을 높이는 필수적인 요소입니다. 델파이와 같은 프로그래밍 언어를 사용할 때, 바람직한 주석 작성 습관을 갖추는 것은 매우 중요합니다. 이는 코드의 완성도를 높일 뿐만 아니라, 코드의 수정 및 보완 시 발생할 수 있는 문제를 줄여줍니다. 주석을 통해 자신의 코드가 무엇을 의도하고 있는지, 어떻게 동작하는지 명확히 설명하고, 후임 개발자가 코드를 분석할 때 발생할 수 있는 혼란을 최소화할 수 있습니다.

결국, 개발자는 코드뿐만 아니라 주석을 통해서도 자신의 개발 의도를 명확히 전달해야 합니다. 이는 자신의 코드가 오랜 시간 동안 유지보수되고, 다른 개발자들에게도 긍정적인 평가를 받을 수 있도록 돕는 중요한 과정입니다.