주석 편집하기

'''주석 (註釋, Comment)'''

주석(註釋)은 원래 “주해”, “해설”, 또는 “설명”을 의미하는 한자어로, 다양한 분야에서 본문이나 자료에 대해 부가적인 설명을 덧붙이는 역할을 한다. 본 문서에서는 프로그래밍 분야에서 사용되는 주석과 문학, 법률, 학술 등 프로그래밍 외 다양한 분야에서의 주석 용례를 폭넓게 다룬다.

{| class="wikitable"
|+ 주석의 어원 및 다국어 표현
! 항목 !! 내용
|-
| 한자 || 註釋 (주해, 해설)
|-
| 영어 || Comment (설명, 논평)
|}

== 개요 ==
주석은 본문의 내용과 별도로 추가적인 정보를 제공하기 위해 삽입되는 설명이나 메모이다. 주석은 그 용도에 따라 다음 두 가지 큰 범주로 나눌 수 있다.

# '''프로그래밍 분야의 주석''': 프로그램의 소스 코드 내에 삽입되어 코드의 기능, 구조, 사용 방법, 또는 수정 이력을 설명하는 용도로 사용된다.
# '''비프로그래밍 분야의 주석''': 문학, 역사, 법률, 학술 등에서 원문이나 자료에 대해 독자의 이해를 돕기 위한 해설, 주해, [[각주]] 등의 형태로 제공된다.

각 분야에서 주석은 독자가 본문을 더 잘 이해할 수 있도록 배경 지식, 해석, 참고 자료 등을 제공하는 중요한 역할을 한다.

== 프로그래밍 분야의 주석 ==
프로그래밍에서 주석은 소스 코드에 포함되어 프로그램의 실행에는 전혀 영향을 미치지 않으며, 주로 코드의 가독성 향상과 유지보수를 목적으로 사용된다.

=== 주요 특징 ===
* '''실행 영향 없음''': 컴파일러나 인터프리터는 주석을 실행하지 않으므로, 프로그램의 동작에는 전혀 관여하지 않는다.
* '''코드 가독성 향상''': 복잡한 알고리즘, 비즈니스 로직, 또는 특수한 처리 방식에 대한 설명을 추가해 코드의 이해도를 높인다.
* '''디버깅 및 유지보수 지원''': 코드의 특정 부분을 임시로 비활성화하거나, 문제의 원인 및 수정 사항을 기록하는 데 유용하다.

=== 장점 ===
* '''코드 이해 용이성''': 주석을 통해 복잡한 로직이나 함수의 목적을 명확하게 설명할 수 있다.
** 예시:
<syntaxhighlight lang="javascript">
checkLogin() // 이 함수는 사용자 로그인 검증을 수행합니다.
</syntaxhighlight>
* '''협업과 유지보수 강화''': 여러 개발자 간의 소통 및 향후 수정 사항 기록에 도움을 준다.
* '''디버깅 보조''': 오류 발생 시 특정 코드 블록을 주석 처리하여 문제의 원인을 추적할 수 있다.

=== 단점 및 주의사항 ===
* '''과도한 주석''': 불필요한 주석은 오히려 코드의 가독성을 해칠 수 있다.
* '''불일치 문제''': 코드가 변경되었음에도 주석이 업데이트되지 않으면 잘못된 정보를 제공할 위험이 있다.
* '''코드 의존성 감소''': 코드 자체가 명확해야 하며, 주석에 지나치게 의존하면 오히려 코드의 자체 이해도가 떨어질 수 있다.

=== 다양한 프로그래밍 언어에서의 주석 작성법 ===

==== Java ====
<syntaxhighlight lang="java">
// 한 줄 주석
/* 여러 줄 주석:
   예) 복잡한 알고리즘의 단계별 설명을 추가할 때 사용 */
/'''
 * JavaDoc 주석:
 * 클래스나 메소드에 대한 설명을 기록하며, 자동 문서화 도구로 HTML 문서를 생성 가능.
 * @param args 명령행 인자
 * @return 반환값에 대한 설명
 */
</syntaxhighlight>

==== 파이썬 ====
<syntaxhighlight lang="python">
# 한 줄 주석

'''
여러 줄 주석:
여러 줄에 걸쳐 설명할 때 사용. 주로 함수나 클래스의 문서화 문자열(docstring)으로 활용됨.
'''

"""
또 다른 여러 줄 주석:
문서화 문자열은 함수나 클래스의 첫 부분에 작성되어, 해당 요소의 사용법과 기능을 설명.
"""
</syntaxhighlight>

==== 자바스크립트 ====
<syntaxhighlight lang="javascript">
// 한 줄 주석

/* 여러 줄 주석:
   예) 복잡한 로직의 각 단계에 대한 설명을 기록할 때 사용 */
</syntaxhighlight>

==== C/C++ ====
<syntaxhighlight lang="c++">
// 한 줄 주석

/* 여러 줄 주석:
   C와 C++에서 기본적으로 사용되는 주석 형식.
   예) 함수의 작동 원리 또는 알고리즘 설명 */
</syntaxhighlight>

==== 기타 언어 ====
* '''Ruby''': <code># 한 줄 주석</code>을 사용하며, 여러 줄 주석은 각 줄마다 `#`를 사용.
* '''HTML''': <code><nowiki><!-- 주석 --></nowiki></code> 형식으로 문서 내 설명을 추가.
* '''SQL''': <code><nowiki>-- 한 줄 주석</nowiki></code> 또는 <code><nowiki>/* 여러 줄 주석 */</nowiki></code> 형식 사용.

=== 주석 작성 가이드라인 (프로그래밍) ===

==== 좋은 주석의 특징 ====
* '''간결하고 명확한 설명'''  
** 불필요한 설명을 피하고, 핵심 내용만을 전달  
** 예시:
<syntaxhighlight>
// 사용자 입력값 검증 함수
</syntaxhighlight>
* '''일관된 형식 유지'''  
** 팀이나 프로젝트의 코딩 컨벤션에 맞춰 동일한 스타일로 작성  
* '''최신성 유지'''  
** 코드 수정 시 주석도 함께 갱신하여 실제 동작과 일치하도록 함  
* '''문맥 제공'''  
** 왜 해당 코드가 작성되었는지, 변경된 이유 등을 간략히 기록  
** 예시:
<syntaxhighlight>
// 이전 방식은 O(n^2) 복잡도를 가졌으므로 최적화 필요
</syntaxhighlight>

==== 피해야 할 주석의 예 ====
* '''너무 당연한 내용의 주석'''  
** 예시:
<syntaxhighlight>
    // i 값을 1 증가시킴
    i++;
</syntaxhighlight>
* '''코드 자체를 반복하는 주석'''  
** 예시:
<syntaxhighlight>
    # 사용자 이름을 출력한다
    print(username)
</syntaxhighlight>
* '''오래된 TODO 주석'''  
** 예시:
<syntaxhighlight>
    // TODO: 이 부분 나중에 수정 (2020년 3월 4일)
    // 버그 수정 필요
</syntaxhighlight>
** 일정 시간이 지나 업데이트되지 않으면 혼란을 초래할 수 있음

==== 자동 문서화 도구 ====
주석을 활용해 자동으로 문서를 생성하는 도구들이 있으며, 이는 API 문서화나 코드 이해에 큰 도움을 준다.
* '''JavaDoc''' (Java): 주석을 기반으로 HTML 문서를 생성
* '''Doxygen''' (C, C++, Java 등): 코드 분석 및 클래스 다이어그램 생성 지원
* '''JSDoc''' (JavaScript): 주석을 통해 API 문서 생성
* '''Sphinx''' (Python): docstring을 활용한 문서화 도구

== 비프로그래밍 분야의 주석 ==
주석은 프로그래밍 외에도 여러 분야에서 본문을 보충하고 해설하는 역할을 한다.

=== 문학 및 고전 연구 ===
* '''문학 주석'''  
** 고전 문학 작품이나 철학, 역사적 문서에 달린 해설  
** 예시: 고전 한문 텍스트에 달린 주해는 독자가 고어와 당시의 문화적 배경을 이해하는 데 도움을 준다.
* '''주해서'''  
** 특정 문헌이나 저서에 대해 전문적으로 해설을 달아놓은 책  
** 예시: 《주역》, 《논어》 등 고전 문헌에 첨부된 주해서는 원문의 의미를 명확하게 전달한다.

=== 법률 및 학술 분야 ===
* '''법률 문서 주석'''  
** 법률 문서나 판례에 대한 해설을 제공하여 법리적 해석을 돕는다.  
** 예시: 각 조항에 대한 해설이 포함된 법령 해설서는 입법 의도와 적용 범위를 명확히 한다.
* '''학술 주석'''  
** 연구 논문이나 학술 서적에서 각주, 미주, 또는 본문 옆의 주석을 통해 추가 정보를 제공  
** 예시: 역사학, 문학 평론, 철학 등에서 인용 문헌이나 추가 설명을 달아 독자의 이해를 돕는다.

=== 예술 및 미디어 분야 ===
* '''영상 주석 (Closed Captioning/Subtitle)'''  
** 영화, TV 프로그램, 온라인 동영상 등에서 대사와 배경 정보를 제공하는 자막  
** 예시: 청각 장애인을 위한 자막은 물론, 추가 설명이나 번역 정보를 제공하기도 한다.
* '''디지털 주석 (Annotations)'''  
** 전자책, 연구 자료, 웹 페이지 등에서 추가적인 설명, 메모, 링크 등을 삽입하여 정보 확장을 돕는다.  
** 예시: 온라인 학술 자료에 포함된 하이퍼링크 주석은 관련 문서로의 접근을 용이하게 한다.

== 주석 작성의 실제 예시 및 실습 ==
아래는 프로그래밍과 비프로그래밍 분야에서 주석을 효과적으로 활용한 예시이다.

=== 예시 1: 프로그래밍 (파이썬) ===
<syntaxhighlight lang="python">
def factorial(n):
    """
    재귀 함수를 사용하여 n의 팩토리얼을 계산합니다.
    
    인자:
      n (int): 0 이상의 정수
    반환값:
      int: n의 팩토리얼 값
    예외:
      ValueError: n이 음수일 경우 예외 발생
    
    예시:
      >>> factorial(5)
      120
    """
    if n < 0:
        raise ValueError("음수는 팩토리얼을 계산할 수 없습니다.")
    if n == 0:
        return 1  # 기본 케이스: 0! = 1
    return n * factorial(n - 1)  # 재귀 호출
</syntaxhighlight>

=== 예시 2: 문학 주석 (고전 텍스트) ===
'''원문:'''
"관물론(觀物論)에서는 자연을 관찰하여 그 이치를 깨닫고자 한다."

'''주석:'''
* '''관물론(觀物論)''' : 자연 현상을 단순히 감상하는 것을 넘어서, 그 내재된 질서와 원리를 탐구하는 철학적 개념을 의미한다.
* '''자연의 이치''' : 자연의 법칙이나 질서를 나타내며, 당시의 철학적, 문화적 배경을 고려할 때 다양한 해석이 가능하다.

=== 예시 3: 법률 문서 주석 ===
'''조문:'''
제10조(표현의 자유)는 모든 국민이 언론, 출판, 집회, 결사의 자유를 가진다.

'''주석:'''
* '''표현의 자유''' : 헌법에서 보장하는 기본권 중 하나로, 개인이 자신의 의견을 자유롭게 표현할 수 있는 권리이다.
* '''제한 사항''' : 다른 사람의 권리 침해나 공공의 안전을 위협하는 경우에는 일정한 제한이 가해질 수 있음.

== 참고 문헌 ==
* [https://www.cimat.mx/ciencia_para_jovenes/bachillerato/libros/%5BKernighan-Ritchie%5DThe_C_Programming_Language.pdf Kernighan, B. W., & Ritchie, D. M. (1988). ''The C Programming Language''. Prentice Hall.]
* [https://dl.ebooksworld.ir/motoman/Refactoring.Improving.the.Design.of.Existing.Code.2nd.edition.www.EBooksWorld.ir.pdf Fowler, M. (1999). ''Refactoring: Improving the Design of Existing Code''. Addison-Wesley.]
* 고전문학 주석 관련 서적 및 연구 논문들

== 관련 문서 ==
* [[프로그래밍 언어]]
* [[코딩 컨벤션]]
* [[소프트웨어 문서화]]
* [[주해 (주석)]]
* [[법률 해설]]

[[분류:프로그래밍]]
[[분류:문학]]
[[분류:법률]]
[[분류:학술 연구]]