주석 편집하기 (부분)

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

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

=== 장점 ===
* '''코드 이해 용이성''': 주석을 통해 복잡한 로직이나 함수의 목적을 명확하게 설명할 수 있다.
** 예시:
<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을 활용한 문서화 도구