주석 - C# 튜토리얼

주석이란 무엇인가

주석은 프로그래머가 코드를 이해하기 쉽게 소스 코드 안에 덧붙인 설명 텍스트입니다. 주석은 실행 코드에 포함되지 않으며 컴파일러가 컴파일할 때 이 내용을 완전히 무시합니다.

문제를 진단할 때 주석을 활용할 수도 있습니다. 오류 원인을 찾지 못할 경우 의심되는 코드 라인을 주석으로 감싸면 컴파일러가 해당 코드를 건너뛰게 돼 단계별로 오류 지점을 분리할 수 있습니다.

주석은 학교 다닐 때 교과서에 적었던 보충 필기와 같다고 생각하면 됩니다. 이런 부가 설명 덕분에 코드의 의도를 훨씬 빠르게 파악할 수 있습니다.

주석의 종류

주석 유형	시작 기호	종료 기호	핵심 규칙
한 줄 주석 Single-line	`//`	현재 줄 끝	오직 해당 줄에만 적용되며 같은 줄에서 `//` 뒤의 모든 내용은 무시됨
블록 주석 (구간 주석) Delimited	`/*`	`*/`	여러 줄 혹은 줄 안 일부 구간을 감쌀 수 있지만 중첩 사용 불가
문서 주석 Documentation	`///`	현재 줄 끝	XML 태그를 내장해 프로젝트 API 문서를 자동 생성하는 데 사용

1. 한 줄 주석 `//`

// 기호부터 현재 줄 맨 끝까지 모든 내용을 컴파일러가 무시함;
줄 맨 앞에 적거나 실행 코드 뒤에 덧붙일 수 있음;
중첩 관련 제약이 없고 /* */ 블록 주석과 문법 충돌이 발생하지 않음.

// 줄 앞 한 줄 주석: 숫자 변수 선언
int num = 10; // 코드 뒤 한 줄 주석: 숫자 10 저장
// int temp = 99; // 전체 줄 주석 처리, 디버깅에 활용. 코드를 지우지 않고 일시 실행 중단 후 나중에 쉽게 복구 가능Code language: JavaScript (javascript)

2. 블록 주석 `/* */`

시작과 종료 기호가 한 쌍으로 사용되며 /*와 */ 사이 모든 내용을 무시함;
여러 줄을 아우르는 작성과 줄 내 부분 주석 처리 모두 지원;
블록 주석 중첩은 금지. 컴파일러가 첫 번째 만나는 */에서 주석을 종료시키고 남은 고립된 */는 문법 오류를 유발함.

예시

/*
여러 줄 블록 주석 예시
컴파일러가 안의 모든 내용을 건너뜀
원하는 만큼 여러 줄 설명을 작성할 수 있음
*/
string str = "테스트";Code language: JavaScript (javascript)

/*
Multi-line delimited comment example
All content here is ignored by the compiler
Text can span any number of lines
wellcome to foxdevelop.com
*/
string greet = "wellcome to foxdevelop.com";
Console.WriteLine(greet);Code language: JavaScript (javascript)

중첩하면 오류가 발생함

블록 주석 안에 또 다른 블록 주석을 적으면 마지막 종료 기호에 맞는 시작 기호가 사라지면서 컴파일 오류가 생깁니다.

줄 내 부분 주석

코드의 일부 구간만 가리는 방식으로 아래 예시에서 변수 a는 주석 처리되었습니다.

int /*a,*/ b; 
// int b; 와 동일하게 동작, 중간의 a, 부분이 주석으로 제외됨Code language: JavaScript (javascript)

잘못된 중첩 블록 주석 예시

컴파일 오류 발생

/* 바깥쪽 주석 시작
    /* 안쪽 중첩 주석 (일반 텍스트로만 인식돼 작동 X) */
// 위 첫 번째 */가 바깥 주석을 닫아버려 아래 남은 */는 매칭되는 시작 기호가 없어 문법 오류 발생
*/Code language: JavaScript (javascript)

`//` 안에 적은 `/*`는 블록 주석으로 인식되지 않음

해당 블록 주석 기호 자체가 한 줄 주석의 일부로 취급되는 상태입니다.

// 이건 한 줄 주석 /* 여기 적은 /*는 일반 문자일 뿐 블록 주석을 열지 않음
int x = 5;
/* 블록 주석 시작 */ // 블록 주석이 여기서 종료되고 뒤의 //는 정상 작동Code language: JavaScript (javascript)

3. 문서 주석 `///`

한 줄 주석과 형태가 비슷하며 슬래시 세 개 ///로 표기함;
XML 태그를 내장할 수 있어 IDE나 개발 툴이 읽어 API 도큐먼트를 자동 생성함;
주로 클래스, 메서드, 속성 위에 작성해 외부 공개 인터페이스를 설명하는 데 사용.

/// <summary>
/// 프로그램 진입점 메인 클래스
/// </summary>
class Program
{
    /// <summary>
    /// 프로그램 실행 진입 메서드
    /// </summary>
    /// <param name="args">명령줄 인자 배열</param>
    static void Main(string[] args)
    {

    }
}Code language: JavaScript (javascript)

정리

블록 주석 /* */는 중첩할 수 없으며 최초로 만나는 */에서 주석 처리가 종료됨;
// 한 줄 주석은 오직 해당 줄에만 적용되고 줄을 넘지 않으며 안에 적은 /*는 그냥 문자로 인식됨;
C#의 한 줄, 블록 주석 문법 동작 방식은 C/C++와 완전히 동일함;
주석 작성 원칙: 코드가 하는 단순 행위를 반복하지 말고 코드의 업무 목적, 설계 의도를 위주로 작성해 유지보수를 쉽게 해야 함. 변수 이름만 복사한 주석은 전혀 활용 가치가 없음.
짧은 한 줄 설명, 일시적인 한 줄 코드 비활성화 → //
여러 줄 코드 일괄 비활성화, 한 줄 안 일부 구간 차단 → /* */
클래스/메서드 인터페이스 설명 작성, 프로젝트 문서 자동 생성 → ///

* 문서 파일 생성 방법

아래 내용은 참고 자료입니다. 문서 주석은 대형 프로젝트에서 주로 사용되므로 학습 단계에서는 존재만 인지하면 충분합니다.

Visual Studio 조작 방법

프로젝트 우클릭 → 속성 → 빌드(Build) 탭;
체크박스 선택: Generate XML documentation file(XML 문서 파일 생성);
기본 출력 경로: bin\Debug\프로젝트명.xml이며 원하는 경로로 변경 가능;
All Configurations(모든 구성)에 체크하면 Debug, Release 모드 모두 XML 파일이 생성됨;
프로젝트를 재빌드하면 해당 폴더에 완전한 XML 주석 파일이 생성됨.

.NET CLI 명령줄 설정 (VS 미설치 시)

프로젝트의 .csproj 파일을 열고 아래 노드를 추가합니다:

&lt;PropertyGroup&gt;
  &lt;GenerateDocumentationFile&gt;true&lt;/GenerateDocumentationFile&gt;
&lt;/PropertyGroup&gt;
Code language: HTML, XML (xml)

빌드 명령 실행:

dotnet build

기능 설명

이 XML 파일에는 <summary>、<param>、<returns> 등 모든 문서용 태그 내용이 저장되어 문서 생성의 원본 데이터가 됩니다. 또한 VS가 이 파일을 읽어 IntelliSense 마우스 오버 팝업에 주석 내용을 표시해줍니다.

기타 문서 생성 툴

마이크로소프트 공식 DocFX (마이크로소프트 추천 툴로 간편하게 정적 HTML 문서 사이트 제작)

Sandcastle (마이크로소프트 구식 툴로 오프라인 CHM 도움말 파일 생성)

서드파티 경량 툴 (Doxygen 등)

위 세 가지 주석 종류 설명 완료

Previous: 숫자 서식 문자열

Next: 형식 선언