주석 (프로그래밍)
"오늘의AI위키"의 AI를 통해 더욱 풍부하고 폭넓은 지식 경험을 누리세요.
1. 개요
주석(프로그래밍)은 소스 코드의 가독성과 유지보수성을 높이기 위해 코드에 추가되는 설명이다. 프로그래밍 언어별로 주석을 표시하는 방식이 다르며, 행 주석과 블록 주석으로 구분된다. 주석은 코드의 설명, 의도 명시, 코드 검토 및 디버깅, 메타데이터 및 지시자 추가, 자동 문서 생성 등 다양한 용도로 사용된다. 주석의 필요성과 내용의 정확성, 세부 수준, 스타일 등은 소스 코드의 대상 독자 및 개발 환경에 따라 달라지며, 코드와 일치하도록 유지하는 것이 중요하다.
다양한 프로그래밍 언어는 각기 다른 주석 문법을 가지고 있으며, 크게 한 줄 주석과 블록 주석으로 나뉜다.
2. 언어 별 주석의 형태
행 주석은 행의 어디에서든 시작할 수 있거나, 행 머리에만 시작 기호를 쓸 수 있다. 행 중간에 종료할 수 없으며, 여러 행에 걸쳐 있을 경우 각 행마다 시작을 지정해야 한다. 반면, 주석의 종료를 지정하지 않아도 된다는 장점이 있다.
블록 주석은 여러 줄 또는 단일 줄의 일부에 걸쳐 있을 수 있는 소스 코드 영역을 구분하며, 시작/종료 구분자로 영역을 지정한다. 일부 언어는 블록 주석의 중첩을 허용하지만, 다른 언어는 허용하지 않는다.
일부 프로그래밍 언어는 블록 주석과 라인 주석을 모두 사용하며, 서로 다른 주석 구분자를 사용한다. 예를 들어, C++는 `/*` 와 `*/`로 구분된 블록 주석과 `//`로 구분된 라인 주석을 사용한다. 다른 언어는 한 종류의 주석만 지원하기도 한다. 예를 들어, 에이다 주석은 `—`로 시작하여 줄의 끝까지 이어지는 라인 주석이다.[6]
대표적인 주석 형태는 다음과 같다.
| 언어 | 주석 형태 |
|---|---|
| C, C++, C 샤프, 자바, 자바 스크립트 | 한 줄 주석은 `//`, 여러 줄 주석은 `/* */` |
| 어셈블리어 | `;` (세미콜론) |
| HTML | ``로 끝남 |
| 파이썬 | 한 줄 주석은 `#`, 여러 줄 주석은 `'''` 또는 `"""` |
| BASIC | `REM` 또는 `’` (작은따옴표) |
| 포트란 | `!` (느낌표) |
| Ada, SQL, Lua | `--` (하이픈 두 개) |
| Lisp, Scheme | `;` (세미콜론) |
| Perl, Ruby, 쉘 스크립트 | `#` (해시 기호) |
| D | `/+` 와 `+/` (중첩 가능한 블록 주석) |
| 파스칼 | `{` 와 `}` 또는 `(*` 와 `*)` |
| PHP | `//`, `#` (한 줄 주석), `/* */` (블록 주석), `/** */` 는 PHPDoc에 사용 |
C/C++ 및 C#에서는 전처리기 지시자 `#if` - `#endif`가 블록 주석을 대신하여 사용되기도 한다.
2. 1. C 계열 언어 (C, C++, C#, Java, JavaScript)
C, C++, C 샤프, 자바, 자바 스크립트에서는 한 줄 주석에 `//`를 사용하고, 여러 줄 주석에는 `/* */`를 사용한다.[3];예제
C 언어에서는 다음과 같이 주석을 사용한다.
/* Hello World라는 문구를 출력 시켜주는
프로그램이다. */
#include
main()
{
printf("Hello World \n"); //Hello World라는 문구를 출력한다.
}
`/*` 와 `*/`를 블록 주석 구분 기호로 사용하는 것은 PL/I에서 C 프로그래밍 언어의 바로 전신인 B 프로그래밍 언어로 상속되었다.[37]
Java에서는 `/** */` 형태의 주석을 사용하여 Javadoc 문서를 생성할 수 있다.
/**
- 이것은 Java의 블록 주석입니다.
- setToolTipText 메서드는 툴팁에 표시할 텍스트를 등록합니다.
- 텍스트는 커서가 컴포넌트 위에 있을 때 표시됩니다.
- @param text 표시할 문자열입니다. 'text'가 null이면
- 이 컴포넌트에 대한 툴팁이 꺼집니다.
- /
public void setToolTipText(String text) {
// 이것은 Java의 인라인 주석입니다. TODO: 이 메서드에 대한 코드를 작성하십시오.
}
C99 이후[62] C 언어 , C++, Java, C#, JavaScript 등에서는 두 개의 슬래시 `//` 이후가 주석으로 간주된다.
C99 이후에는 C++에서 사용되는 `//` 구문을 사용하여 한 줄 주석을 사용하는 것도 가능해졌다.
/*
- 최대 프로세스 제한을 초과했는지 확인하지만, root는 제외해야 합니다.
- 이는 로그인 및 관련 프로그램이 사용자별 프로세스 제한을 root가 실행 중인 프로세스 수보다 낮게 설정할 수 있도록 하기 위해 필요합니다. -- Rik
- /
if (atomic_read(&p->user->processes) >= p->rlim[RLIMIT_NPROC].rlim_cur
&& !capable(CAP_SYS_ADMIN) && !capable(CAP_SYS_RESOURCE))
goto bad_fork_free;
2. 2. 어셈블리어
어셈블리어에서 주석은 `;` (세미콜론)으로 시작한다.2. 3. HTML
HTML에서 주석은 ``로 끝난다.[1] SGML과의 호환성을 위해 주석 내에서 "--" (이중 하이픈) 문자열은 허용되지 않는다.[1]예제:
```html
주석
```
위키에서는 원칙적으로 `` 로 묶는다.[1]
2. 4. 파이썬
파이썬의 경우 한 줄 주석은 `#` 기호를 사용하고, 여러 줄 주석은 `'''` (작은따옴표 3개) 또는 `"""` (큰따옴표 3개)를 사용한다.'''예제'''
```python
'''Hello World! 라는 문구를
출력시켜주는 프로그램이다.'''
print("Hello World!") #출력
```
파이썬의 한 줄 주석은 `#` 기호를 사용하며, 아래 코드에서 두 가지 예시를 볼 수 있다.
```python
# 이 프로그램은 화면에 "Hello World"를 출력합니다.
print("Hello World!") # 새로운 문법에 주목하세요
```
파이썬에서 삼중 따옴표로 묶인 문자열은 블록 주석과 비슷한 역할을 하지만, 기술적으로는 블록 주석이 아니며[52] 문자열 리터럴로 취급된다.[53] 인터프리터에 의해 완전히 무시되지 않으며, docstring으로도 사용될 수 있다.
```python
"""
이것이 mymodule.py 파일이라고 가정하면, 파일의 첫 번째 문장인 이 문자열은
파일을 가져올 때 "mymodule" 모듈의 docstring이 됩니다.
"""
class MyClass:
"""클래스의 docstring"""
def my_method(self):
"""메서드의 docstring"""
def my_function():
"""함수의 docstring"""
2. 5. BASIC
BASIC에서는 `REM` 또는 `’` (작은따옴표)로 주석을 시작한다.[62] `REM`은 명령어 중 하나이므로, 행 중간부터 주석으로 처리하려면 콜론(`:`)을 사용하여 멀티 스테이트먼트 형태로 작성해야 한다. 반면 `’`는 `:REM`의 생략형으로 간주되므로 앞에 `:`을 붙일 필요가 없다.다음은 고전적인 초기 BASIC 코드 예시이다.
```basic
10 REM 이 BASIC 프로그램은 PRINT 및 GOTO 문의 사용법을 보여줍니다.
15 REM "HELLO" 문구로 화면을 채웁니다.
20 PRINT "HELLO"
30 GOTO 20
```
Quick Basic, Q Basic, Visual Basic, Visual Basic .NET, VB Script를 포함한 이후의 Microsoft BASIC, 그리고 FreeBASIC 및 Gambas와 같은 후손 버전에서는 ' (작은 따옴표) 문자 뒤의 줄에 있는 모든 텍스트도 주석으로 처리된다.
다음은 Visual Basic .NET의 코드 예시이다.
```vbnet
Public Class Form1
Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
' 사용자가
' 프로그램 창에서 버튼을 클릭했을 때 다음 코드가 실행됩니다.
rem 주석은 여전히 존재합니다.
MessageBox.Show("Hello, World") ' 인사를 담은 팝업 창을 표시합니다.
End Sub
End Class
2. 6. Fortran
Fortran IV 코드에서는 1열에 "C" 문자가 있으면 전체 줄이 주석으로 처리된다.[1]다음은 주석 사용 예시이다.
C
C 'C'(첫 번째 또는 '주석' 열)로 시작하는 줄은 주석입니다.
C
WRITE (6,610)
610 FORMAT(12H HELLO WORLD)
END
포트란에서는 느낌표(!) 뒤의 모든 문자는 주석으로 간주된다.[2]
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
!* 느낌표 뒤의 모든 문자는 주석으로 간주됩니다. *
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
program comment_test
print '(A)', 'Hello world' ! 포트란 90은 인라인 주석 옵션을 도입했습니다.
end program
포트란 90에서는 인라인 주석 옵션이 도입되었다.[2]
2. 7. 기타 언어
Ada, SQL, Lua에서는 `--` (하이픈 두 개)를 사용하여 주석을 표시한다.[6] Ada 코드 예시는 다음과 같다.```ada
- - 관제 업무는 이륙 및 착륙 요청을 받습니다.
task type Controller (My_Runway: Runway_Access) is
- - 동기 메시지 전달을 위한 작업 항목
entry Request_Takeoff (ID: in Airplane_ID; Takeoff: out Runway_Access);
entry Request_Approach(ID: in Airplane_ID; Approach: out Runway_Access);
end Controller;
```
Lua에서도 `--`를 사용하며, 블록 주석은 `--`로 시작하여 ``로 끝난다.
```lua
- -
긴 주석
]]
print(20) -- 결과를 출력
```
Lisp과 Scheme에서는 `;` (세미콜론) 이후가 주석으로 간주된다.[62]
Perl, Ruby, 쉘 스크립트에서는 `#` (해시 기호) 이후가 주석으로 처리된다.[62] Perl 예시는 다음과 같다.
```perl
# 간단한 예시
#
my $s = "Wikipedia"; # 변수 s를 "Wikipedia"로 설정합니다.
print $s . "\n"; # 출력 후 개행 문자를 추가합니다.
```
D는 `/+` 와 `+/` 를 사용하여 중첩 가능한 블록 주석을 지원한다.[44]
```d
// 이것은 한 줄 주석입니다.
/* 이것은 여러 줄 주석입니다.
- /
/+ 이것은
/+ 중첩된 +/
주석입니다 +/
```
파스칼에서는 `{` 와 `}` 또는 `(*` 와 `*)` 를 사용한다.[46]
```pascal
(* 대각선 테스트 *)
columnDifference := testColumn - column;
if (row + columnDifference = testRow) or
.......
```
PHP에서는 `//`, `#` (한 줄 주석), `/* */` (블록 주석)을 사용하며, `/** */` 는 PHPDoc에 사용된다.[51]
```php
/**
- 이 클래스는 샘플 문서를 포함합니다.
- @author Unknown
- /
#[Attribute]
class MyAttribute {
const VALUE = 'value';
// 이것은 인라인 주석입니다. C++와 같이 '//'로 시작합니다.
private $value;
# 이것은 '#'로 시작하는 유닉스 스타일 인라인 주석입니다.
public function __construct($value = null) {
$this->value = $value;
}
/*
이것은 여러 줄 주석입니다.
이 주석은 중첩될 수 없습니다.
- /
}
3. 주석의 용도
주석은 프로그램의 공동 개발이나 소스 코드 보수 관리에 필수적이다. 프로그램 안에 주석으로 문서를 포함하면 팀을 이루어 작업하거나 보수할 때 도움이 된다.[64] 담당자가 바뀌어도 보수, 개량, 버그 수정에 유리하다. 단, 이는 "올바른 주석"을 썼을 때의 이야기다. 잘못된 주석은 해독을 방해하거나 오해를 일으킨다.
주석의 좋고 나쁨은 독자의 지식이나 주관에 따라 다르므로, 어떤 주석이 적절한지 딱 잘라 말할 수 없다. 코드 각 단계에서 무엇을 실행하는지 일일이 설명하는 주석은 장황하거나 기억 장소를 낭비하고 읽기 어려울 수 있지만, 초심자를 위한 예시 코드로는 도움이 될 수 있다.
코드 본문을 읽으면 "무엇을 실행하는가"는 알 수 있으므로, 주석에는 "왜 그러한 코드를 썼는가"라는 설계 이유를 쓰는 것이 좋다는 방법론도 있다.[64]
3. 1. 코드 설명 및 의도 명시
주석은 코드의 작동 방식, 목적, 작성 이유 등을 설명하여 다른 개발자(미래의 자신 포함)가 코드를 쉽게 이해하도록 돕는 역할을 한다. 특히 복잡한 알고리즘이나 중요한 결정 사항에 대한 설명을 추가하는 것이 좋다.[7][8]주석은 실제 코드를 작성하기 전에 의도를 개략적으로 설명하는 의사 코드의 형태로 사용될 수 있다. 아래는 C++ 코드 예시이다.
/* 서버에서 반환된 모든 요소를 역순으로 반복합니다.
(요소는 시간 순서대로 처리되어야 합니다) */
for (i = (numElementsReturned - 0); i >= 1; i--) {
/* 각 요소의 데이터를 처리합니다 */
updatePattern(i, returnedElements[i]);
}
이러한 유형의 주석은 의도된 결과와 코드를 직접 비교할 수 있도록 하여 검토 과정을 단순화한다.[7][8]
주석은 코드를 요약하거나 프로그래머의 의도를 설명하는 데 사용될 수 있다. 코드를 평이한 영어로 다시 설명하는 것은 불필요하며, 코드가 복잡하거나 명명법이 좋지 않다는 신호일 수 있다.[9][10]
:"나쁜 코드는 문서화하지 말고, 다시 작성하라."[9]
:"좋은 주석은 코드를 반복하거나 설명하지 않습니다. 주석은 코드의 의도를 명확히 합니다. 주석은 코드보다 더 높은 수준의 추상화로, 무엇을 하려고 하는지 설명해야 합니다."[10]
주석은 코드 블록이 관례나 모범 사례에 맞지 않는 이유를 설명하는 데 사용될 수 있다. 아래는 VBscript 코드 예시이다.
' 양식 데이터를 재사용할 때 발생하는 서버 오류 때문에 두 번째 변수 사용.
' 서버 동작 문제에 대한 문서는 없으므로, 그냥 우회해서 코딩함.
vtx = server.mappath("local settings")
경우에 따라 소스 코드는 특정 문제에 대한 새롭거나 주목할 만한 해결책을 담고 있으며, 주석은 방법론에 대한 설명을 포함할 수 있다. 이러한 설명에는 다이어그램, 형식적인 수학적 증명이 포함될 수 있다.[11]
예를 들어, 프로그래머는 삽입 정렬이 이론적으로 퀵 정렬보다 느리지만, 삽입 정렬을 선택한 이유를 설명하기 위해 주석을 추가할 수 있다. 아래는 Java 코드 예시이다.
```java
list = [f (b), f (b), f (c), f (d), f (a), ...];
// 안정적인 정렬이 필요합니다. 게다가 성능은 정말 중요하지 않습니다.
insertion_sort (list);
```
로고, 다이어그램 및 순서도는 ASCII 아트로 구성되어 주석 형식으로 소스 코드에 삽입될 수 있다.[12] 저작권 고지도 주석으로 소스 코드 내에 포함될 수 있다.
어떤 언어를 사용하여 소스 코드를 작성하든, 작성자가 아닌 다른 사람이 읽거나, 본인이라도 시간이 지난 후에 읽는 경우에는, 소스 코드에서 그 의도를 정확하게 파악하기 어려울 수 있다. 이러한 이유로, 소스 코드의 의도를 주석으로 소스 코드 내에 삽입하는 것이 도움이 된다.
3. 2. 코드 검토 및 디버깅
코드 검토 및 디버깅 과정에서 주석은 특정 코드 블록의 역할을 설명하거나, 임시로 코드를 비활성화하는 데 사용될 수 있다. 이를 "주석 처리"라고 한다.개발자들은 코드의 특정 부분을 주석 처리하여 최종 프로그램에서 실행되지 않도록 한다. 이는 오류의 원인을 찾기 위해 사용될 수 있다. 프로그램의 일부를 체계적으로 주석 처리하고 실행함으로써 오류의 원인을 파악하고 수정할 수 있다.[60]
많은 IDE에서는 단일 메뉴 옵션이나 키 조합으로 주석을 빠르게 추가하거나 제거할 수 있다. 프로그래머는 주석 처리할 텍스트 부분을 표시하고 적절한 옵션을 선택하면 된다.
일시적으로 코드를 비활성화하기 위해 삭제하는 대신 주석으로 처리하는 경우가 많다. 이를 "코멘트 아웃(comment-out)"이라고 한다[60]。 주석 안에 또 다른 주석이 있을 수 있으므로, 주석의 중첩 가능 여부는 중요하다. 주석을 해제하여 코드를 다시 활성화하는 것을 "언코멘트(uncomment)"라고 한다[61]。
3. 3. 메타데이터 및 지시자
주석은 코드 작성자, 작성일, 소프트웨어 라이선스 등의 메타데이터를 저장하는 데 사용될 수 있다.[12] 많은 소프트웨어 관리자들은 해당 프로그램의 소스 코드를 읽는 사람들이 개선 사항을 관리자에게 다시 보낼 수 있도록 돕기 위해 제출 지침을 주석에 넣기도 한다.다른 메타데이터로는 프로그램 파일의 최초 버전을 만든 사람의 이름과 최초 버전이 생성된 날짜, 현재 프로그램 관리자의 이름, 지금까지 프로그램 파일을 편집한 다른 사람들의 이름, 프로그램 사용 방법에 대한 설명서의 URL 등이 있다. 프로그램의 일부 섹션에 있는 알고리즘이 참고 자료에 기반한 경우, 주석을 사용하여 책의 페이지 번호와 제목 또는 RFC(Request for Comments) 등을 제공할 수 있다.
일부 컴파일러나 인터프리터는 주석을 사용하여 특정 기능을 활성화하거나 설정을 변경하는 지시어를 처리하기도 한다.
예시는 다음과 같다.
- 유닉스 "shebang" - `#!` - 스크립트의 첫 번째 줄에서 사용될 인터프리터를 가리킨다.
- 소스 파일이 사용하고 있는 인코딩을 식별하는 "매직 주석",[21] 예를 들어 파이썬의 PEP 263.[22]
아래의 Python 스크립트는 유닉스 계열 시스템에서 인터프리터 지정과 인코딩 설정의 두 가지 사용법을 모두 보여준다.
```python
#!/usr/bin/env python3
# -*- coding: UTF-8 -*-
print("Testing")
```
C에서 주석을 사용하여 case 문에서 기본 "fallthrough"가 의도적으로 수행되었음을 컴파일러에 알리는 경우도 이와 유사하다.[23]
3. 4. 자동 문서 생성
프로그래밍 도구는 때때로 주석에 설명서와 메타데이터를 저장한다.[14] 설명서를 소스 코드 주석 내에 유지하는 것은 설명서 프로세스를 단순화하고 설명서가 코드 변경 사항과 함께 최신 상태로 유지될 가능성을 높이는 한 가지 방법으로 간주된다.[17]설명서 생성기의 예로는 Java와 함께 사용되는 Javadoc, D의 Ddoc, C, C++, Java, IDL의 Doxygen, PL/SQL, Transact-SQL, PowerBuilder의 Visual Expert, PHP의 PHPDoc 프로그램이 있다. docstring 형태는 Python, Lisp, Elixir, Clojure에서 지원된다.[18]
C#, F# 및 Visual Basic .NET은 컴파일된 .NET 어셈블리에서 IntelliSense가 읽는 "XML 주석"이라는 유사한 기능을 구현한다.[19]
다음은 `setToolTipText` 메서드를 설명하기 위해 사용된 블록 주석을 보여주는 Java 코드 조각이다. 형식은 썬 마이크로시스템즈 Javadoc 표준과 일치한다. 주석은 Javadoc 프로세서에서 읽을 수 있도록 설계되었다.
```java
/**
- 이것은 Java의 블록 주석이다.
- setToolTipText 메서드는 툴팁에 표시할 텍스트를 등록한다.
- 텍스트는 커서가 컴포넌트 위에 있을 때 표시된다.
- @param text 표시할 문자열이다. 'text'가 null이면
- 이 컴포넌트에 대한 툴팁이 꺼진다.
- /
public void setToolTipText(String text) {
// 이것은 Java의 인라인 주석이다. TODO: 이 메서드에 대한 코드를 작성하십시오.
}
```
PHP의 주석은 C++ 스타일(인라인 및 블록 모두) 또는 해시를 사용할 수 있다. PHPDoc는 Javadoc에서 채택된 스타일이며 PHP 코드 문서화를 위한 일반적인 표준이다.
PHP 8부터는 # 기호가 '[' 바로 뒤에 오지 않는 경우에만 주석을 의미할 수 있다. 그렇지 않으면 ']'까지 실행되는 함수 속성을 의미한다.
```php
/**
- 이 클래스는 샘플 문서를 포함한다.
- @author Unknown
- /
#[Attribute]
class MyAttribute {
const VALUE = 'value';
// 이것은 인라인 주석이다. C++와 같이 '//'로 시작한다.
private $value;
# 이것은 '#'로 시작하는 유닉스 스타일 인라인 주석이다.
public function __construct($value = null) {
$this->value = $value;
}
/*
이것은 여러 줄 주석이다.
이 주석은 중첩될 수 없다.
- /
}
4. 주석 작성 시 고려 사항
오픈 소스/클로즈드 소스를 불문하고, 주석은 프로그램의 공동 개발이나 소스 코드의 유지보수 관리에 필수적이다. 특히 프로그램 내에 주석으로 문서를 포함함으로써, 팀을 이루어 공동 작업하거나 유지보수하는 데에 도움이 된다. 또한, 담당자가 바뀐 후에도 유지보수, 개량, 또는 버그 수정에 큰 힘을 발휘한다. 다만, 그것은 "올바른 주석"이 있다는 전제하에서만 그렇다. 잘못된 주석은 해독을 방해하거나 오해를 일으키는 원인이 되기도 한다.[64]
주석의 좋고 나쁨은 독자의 전제 지식이나 주관과도 관련되므로, 어떤 주석이 적절한지는 일률적으로 말할 수 없다. 프로그램 코드의 각 단계에서 무엇을 실행하고 있는지를 자연어로 일일이 설명하는 주석은 "장황하다", "기억 영역을 쓸데없이 낭비한다", "읽기 어려워진다" 등의 단점을 내포할 가능성도 있지만, 초심자나 입문자를 위한 샘플 코드로는 도움이 될 수도 있다.
프로그램 코드 본문을 읽으면 "무엇을 실행하고 있는가"는 알 수 있으므로, 주석에는 "무엇을 실행하고 있는가"보다는 "왜 그러한 코드를 썼는가"라는 설계 이유를 기술해야 한다는 방법론도 있다.[64]
4. 1. 주석의 필요성
주석은 코드의 가독성을 높이고 다른 개발자나 미래의 자신이 코드를 이해하는 데 도움을 줄 수 있다.[7][8] 특히, 오픈 소스 프로젝트나 협업 환경에서 주석은 코드의 의도와 배경을 설명하여 효율적인 공동 작업을 가능하게 한다.[64]하지만 주석의 사용에 대해서는 다양한 의견이 존재한다.[7][8] 코드를 평이한 언어로 다시 설명하는 것은 불필요하며, 코드가 복잡하다면 주석을 추가하기보다 코드를 다시 작성해야 한다는 견해도 있다.[9]
:"나쁜 코드는 문서화하지 말고, 다시 작성하라."[9]
:"좋은 주석은 코드를 반복하거나 설명하지 않는다. 주석은 코드의 의도를 명확히 한다. 주석은 코드보다 더 높은 수준의 추상화로, 무엇을 하려고 하는지 설명해야 한다."[10]
주석은 코드 블록이 일반적인 방식과 다르게 보이는 이유를 설명하는 데 사용될 수 있다. 예를 들어, 개발 시간이 촉박하거나 버그 수정을 위해 임시방편으로 작성된 코드의 경우 주석을 통해 그 이유를 설명할 수 있다.
일반적인 개발 관행 중 하나는 코드의 일부분을 ''주석 처리''하여 일시적으로 실행되지 않도록 하는 것이다. 이는 특정 코드 조각을 제외하거나 오류의 원인을 찾을 때 유용하게 사용될 수 있다. 많은 IDE에서는 이러한 주석 처리를 쉽게 할 수 있는 기능을 제공한다.
소스 코드 주석의 적절한 사용에 대한 다양한 규범적 관점과 오랜 견해가 존재한다.[26][27] 어떤 사람들은 자기 문서화를 주장하며 주석을 최소화해야 한다고 주장하는 반면,[9] 다른 사람들은 코드를 광범위하게 주석 처리해야 한다고 제안한다.[30][31]
이러한 견해의 중간에는 주석 자체가 유익하거나 해로운 것이 아니라, 주석이 정확하고 소스 코드와 동기화되어 유지되는 것이 중요하다는 주장이 있다.[32][33]
주석은 때때로 프로그래밍의 계약에 의한 설계 접근 방식에서 계약을 문서화하는 데 사용되기도 한다.
어떤 언어를 사용하든, 코드를 작성한 사람이 아닌 다른 사람이나, 시간이 지난 후의 자신이 코드를 읽을 때, 코드의 의도를 정확하게 파악하기 어려울 수 있다. 따라서 소스 코드 내에 주석으로 의도를 명시하는 것이 도움이 된다.
프로그램 코드의 각 단계에서 무엇을 실행하고 있는지를 일일이 설명하는 주석은 장황하고 읽기 어려울 수 있지만, 초심자를 위한 샘플 코드로는 도움이 될 수 있다. 프로그램 코드 본문을 통해 "무엇을 실행하고 있는가"는 알 수 있으므로, 주석에는 "왜 그러한 코드를 썼는가"라는 설계 이유를 기술해야 한다는 방법론도 있다.[64]
4. 2. 내용의 정확성 및 최신 유지
주석은 코드와 동기화되어야 하며, 코드 변경 시 주석도 함께 업데이트해야 한다. 그렇지 않으면 잘못된 정보나 오래된 주석은 혼란을 야기할 수 있다.[64]4. 3. 세부 수준
주석의 세부 수준과 설명은 코드의 대상 독자 및 기타 고려 사항에 따라 달라질 수 있다.예를 들어, 초보 프로그래밍 학습자를 위한 입문서에는 다음 Java 주석이 적합할 수 있다.
```java
String s = "Wikipedia"; /* 변수 s에 값 "Wikipedia"를 할당합니다. */
```
그러나 이 수준의 세부 정보는 실제 제품 코드나 숙련된 개발자가 관련된 상황에는 적절하지 않다. 이러한 기본적인 설명은 "좋은 주석은 ... 의도를 명확히 한다."[10]라는 지침과 일치하지 않는다. 또한 전문적인 코딩 환경에서는 비즈니스 운영에서 정의된 특정 성능 요구 사항을 충족하기 위해 세부 수준이 일반적으로 잘 정의되어 있다.[31]
오픈 소스/클로즈드 소스를 불문하고, 주석은 프로그램의 공동 개발이나 소스 코드의 유지보수 관리에 필수적이다. 특히 프로그램 내에 주석으로 문서를 포함함으로써, 팀을 이루어 공동 작업하거나 유지보수하는 데 도움이 된다. 또한, 담당자가 바뀐 후에도 유지보수, 개량 또는 버그 수정에 큰 힘을 발휘한다. 다만, "올바른 주석"이 있다는 전제하에서만 그렇다. 잘못된 주석은 해독을 방해하거나 오해를 일으키는 원인이 되기도 한다.
주석의 좋고 나쁨은 독자의 전제 지식이나 주관과도 관련되므로, 어떤 주석이 적절한지는 일률적으로 말할 수 없다. 프로그램 코드의 각 단계에서 무엇을 실행하고 있는지를 자연어로 일일이 설명하는 주석은 "장황하다", "기억 영역을 쓸데없이 낭비한다", "읽기 어려워진다" 등의 단점을 내포할 가능성도 있지만, 초심자나 입문자를 위한 샘플 코드로는 도움이 될 수도 있다.
프로그램 코드 본문을 읽으면 "무엇을 실행하고 있는가"는 알 수 있으므로, 주석에는 "무엇을 실행하고 있는가"보다는 "왜 그러한 코드를 썼는가"라는 설계 이유를 기술해야 한다는 방법론도 있다.[64]
4. 4. 스타일
코드 스타일과 마찬가지로 주석 스타일도 일관성을 유지하는 것이 중요하다. 팀이나 조직 내에서 주석 작성 규칙을 정하고 따르는 것이 좋다.여러 명의 개발자가 참여하는 대규모 프로젝트의 경우, 주석 스타일은 프로젝트 시작 전에 합의되거나 프로젝트가 진행됨에 따라 관례 또는 필요에 따라 발전한다. 일반적으로 프로그래머는 일관되고 방해가 되지 않으며, 수정하기 쉽고, 깨뜨리기 어려운 스타일을 선호한다.[34]
다음은 C 언어에서 주석 스타일이 얼마나 다양할 수 있는지 보여주는 예제이다. 기본적인 정보는 동일하게 전달하면서도 스타일이 다를 수 있다.
/*
이것은 주석 본문입니다.
변형 1.
- /
/***\
- *
- 이것은 주석 본문입니다. *
- 변형 2. *
- *
\***/
개인의 선호도, 소스 코드 편집기의 유연성 및 기타 고려 사항과 같은 요소는 소스 코드에서 사용되는 스타일 변형에 영향을 미치는 경향이 있다. 예를 들어, 변형 2는 주석의 텍스트 정렬 및 시각적 모양을 자동화할 수 있는 소스 코드 편집기가 없는 프로그래머들 사이에서는 선호되지 않을 수 있다.
소프트웨어 컨설턴트이자 기술 평론가인 앨런 홀럽[35]은 주석의 왼쪽 가장자리를 정렬하는 것을 옹호하는 전문가 중 한 명이다:[36]
/* 이것은 홀럽이 C와 C++에 권장하는 스타일입니다.
- 그의 저서 ''Enough Rope'' 규칙 29에 나와 있습니다.
- /
/* 이것은 C에서도 사용할 수 있는 또 다른 방법입니다.
- * 주석의 두 번째 줄부터 마지막 줄까지를 첫 번째 줄에서 한 칸 자동으로 들여쓰기 하지 않는 편집기에서 더 쉽게 사용할 수 있습니다.
- * 홀럽의 책 규칙 31에서도 사용됩니다.
- /
`/*` 와 `*/`를 블록 주석 구분 기호로 사용하는 것은 PL/I에서 C 프로그래밍 언어의 바로 전신인 B 프로그래밍 언어로 상속되었다.[37]
라인 주석은 일반적으로 주석의 시작을 나타내는 임의의 구분자 또는 토큰 시퀀스를 사용하고, 주석의 끝을 나타내는 개행 문자를 사용한다.
아래 예에서 ASCII 문자 `//`부터 줄 끝까지의 모든 텍스트는 무시된다.
// -------------------------
// This is the comment body.
// -------------------------
많은 언어에서는 명령줄과 함께 주석을 "인라인"으로 넣어서 주석을 추가하는 것도 가능하다.
print $s . "\n"; # Add a newline character after printing
만약 언어에서 라인 주석과 블록 주석을 모두 허용한다면, 프로그래밍 팀은 이를 다르게 사용하는 관례를 정할 수 있다. 예를 들어 라인 주석은 사소한 주석에만 사용하고, 블록 주석은 더 높은 수준의 추상화를 설명하는 데 사용할 수 있다.
오픈 소스/클로즈드 소스를 불문하고, 주석은 프로그램의 공동 개발이나 소스 코드의 보수 관리에 필수적이다. 특히 프로그램 내에 주석으로 문서를 포함함으로써, 팀을 이루어 공동 작업하거나 보수하는 데에 도움이 된다. 또한, 담당자가 바뀐 후에도 보수, 개량, 또는 버그 수정에 큰 힘을 발휘한다. 다만, 그것은 "올바른 주석이 기술되어 있다"는 전제하의 이야기이다. 잘못된 주석이 적혀 있는 경우, 해독을 방해하거나 오해를 일으키는 원인이 되기도 한다.
주석의 좋고 나쁨은 독자의 전제 지식이나 주관과도 관련되므로, 어떤 주석이 적절한지는 일률적으로 말할 수 없다. 프로그램 코드의 각 스텝 행에서 무엇을 실행하고 있는지를 자연어로 일일이 설명하는 듯한 주석은 "장황하다", "기억 영역을 쓸데없이 낭비한다", "읽기 어려워진다" 등의 단점을 내포할 가능성도 있지만, 초심자나 입문자를 위한 샘플 코드로는 도움이 될 수도 있다.
프로그램 코드의 본문을 읽으면 "무엇을 실행하고 있는가" 자체는 알 수 있으므로, 주석에는 "무엇을 실행하고 있는가"를 기술하기보다는, "왜 그러한 코드를 썼는가"라는 설계 이유를 기술해야 한다는 방법론도 있다.[64]
참조
[1]
서적
Software Maintenance: Concepts and Practice
World Scientific
[2]
서적
Making Use of Jsp
Wiley
[2]
서적
Java for Coldfusion Developers
Pearson Education
[3]
서적
Computer Fundamentals and Programming in C
Laxmi Publications
[4]
서적
MATLAB Guide
SIAM
[5]
서적
The Elements of Java Style
https://archive.org/[...]
Cambridge University Press
[6]
웹사이트
Using the right comment in Java
http://javadude.com/[...]
2000-03-04
[7]
서적
Applied Pattern Recognition: Algorithms and Implementation in C++
Springer
[8]
서적
Software Engineering Handbook
CRC Press
[9]
문서
The Elements of Programming Style
[10]
문서
Code Complete
[11]
서적
Code reading: The Open Source Perspective
Addison-Wesley
[12]
웹사이트
CodePlotter 1.6 – Add and edit diagrams in your code with this 'Visio-like' tool
http://www.codeproje[...]
2007-07-24
[13]
서적
Web Design in a Nutshell: A Desktop Quick Reference
O'Reilly
[14]
서적
Mac OS X for Photographers: Optimized Image Workflow for the Mac User
https://archive.org/[...]
Focal Press
[15]
서적
Learning the VI Editor
https://archive.org/[...]
O'Reilly & Associates
[16]
서적
Practical Subversion, Second Edition
APress
[17]
서적
The Object Primer: Agile Model-Driven Development with UML 2.0
Cambridge University Press
[18]
URL
Function definition with docstring in Clojure
https://clojure.gith[...]
[19]
서적
C# 2005
[20]
문서
c2: HotComments
[21]
웹사이트
class Encoding
https://docs.ruby-la[...]
ruby-lang.org
2018-12-05
[22]
웹사이트
PEP 263 – Defining Python Source Code Encodings
https://www.python.o[...]
Python.org
2018-12-05
[23]
웹사이트
-Wimplicit-fallthrough in GCC 7
https://developers.r[...]
Red Hat
2017-03-10
[24]
웹사이트
Microsoft Programmers Hid A Bunch Of Profanity In Early Software Code
https://www.business[...]
2014-03-27
[25]
URL
Linux Swear Count
http://www.vidarhole[...]
[26]
서적
Code Craft
No Starch Press
[27]
서적
Intermediate Programming Principles and Techniques Using Pascal
West Pub. Co
[28]
서적
Oracle Developer Advanced Forms & Reports
Osborne/McGraw-Hill
[29]
웹사이트
Worst Practice - Bad Comments
http://www.sqlserver[...]
2007-07-24
[30]
서적
Java, Java, Java: object-oriented problem solving
Prentice Hall College
[31]
웹사이트
How to Write Doc Comments for the Javadoc Tool
http://java.sun.com/[...]
2007-07-24
[32]
서적
Techniques of Program Structure and Design
University of Michigan
[33]
서적
C++ Gotchas: Avoiding Common Problems in Coding and Design
Addison-Wesley Professional
[34]
웹사이트
Coding Style
http://developer.gno[...]
2007-07-24
[35]
웹사이트
Allen Holub
http://www.holub.com[...]
2007-07-24
[36]
서적
Enough Rope to Shoot Yourself in the Foot
McGraw-Hill
[37]
웹사이트
Users' Reference to B
https://www.bell-lab[...]
2017-07-21
[38]
간행물
PEP 0350 – Codetags
https://www.python.o[...]
Python Software Foundation
[39]
웹사이트
Never Forget Anything Before, After and While Coding
https://medium.com/@[...]
[40]
웹사이트
Using the Task List
https://msdn.microso[...]
msdn.microsoft.com
[41]
웹사이트
Leave a comment in running-config
https://learningnetw[...]
[42]
웹사이트
Managing Configuration Files Configuration Guide, Cisco IOS XE Release 3S (ASR 900 Series)
http://www.cisco.com[...]
[43]
웹사이트
Literate programming
http://www.haskell.o[...]
[44]
웹사이트
Programming in Lua 1.3
http://www.lua.org/p[...]
2017-11-08
[45]
웹사이트
macros.extractDocCommentsAndRunnables
https://nim-lang.git[...]
[46]
서적
Pascal User Manual and Report
Springer-Verlag
[47]
서적
Programming in Modula-2
Springer-Verlag
[48]
서적
Programming in Oberon
Addison-Wesley
[49]
웹사이트
perldoc – the Plain Old Documentation format
http://perldoc.perl.[...]
2011-09-12
[50]
웹사이트
Pod::ParseUtils – helpers for POD parsing and conversion
http://search.cpan.o[...]
2011-09-12
[51]
웹사이트
Perl 6 Documentation – Syntax (Comments)
https://docs.perl6.o[...]
2017-04-06
[52]
웹사이트
Python 3 Basic Syntax
https://web.archive.[...]
2019-02-25
[53]
뉴스
Python tip: You can use multi-line strings as multi-line comments
https://twitter.com/[...]
Guido van Rossum
2011-09-11
[54]
서적
Microsoft SQL Server 7
https://archive.org/[...]
Prima Publishing
[55]
웹사이트
MySQL 8.0 Reference Manual
https://dev.mysql.co[...]
Oracle Corporation
2020-01-02
[56]
웹사이트
SQL As Understood By SQLite
https://www.sqlite.o[...]
SQLite Consortium
2020-01-02
[57]
웹사이트
PostgreSQL 10.11 Documentation
https://www.postgres[...]
The PostgreSQL Global Development Group
2020-01-02
[58]
웹사이트
Oracle® Database SQL Reference
https://docs.oracle.[...]
Oracle Corporation
2020-01-02
[59]
서적
Surviving Security: How to Integrate People, Process, and Technology
CRC Press
[60]
웹사이트
comment outの意味・使い方｜英辞郎 on the WEB
https://eow.alc.co.j[...]
[61]
웹사이트
uncommentの意味・使い方｜英辞郎 on the WEB
https://eow.alc.co.j[...]
[62]
웹사이트
Ruby 2.5.0 リファレンスマニュアル > Rubyで使われる記号の意味
https://docs.ruby-la[...]
[63]
웹사이트
GetPrivateProfileSection function (winbase.h) - Win32 apps | Microsoft Learn
https://learn.micros[...]
[64]
웹사이트
10:コメントには「なぜ」を書く — 自走プログラマー【抜粋版】
https://jisou-progra[...]
[65]
서적
Software Maintenance: Concepts and Practice
https://archive.org/[...]
World Scientific
[66]
서적
Making Use of Jsp
https://archive.org/[...]
Wiley
본 사이트는 AI가 위키백과와 뉴스 기사,정부 간행물,학술 논문등을 바탕으로 정보를 가공하여 제공하는 백과사전형 서비스입니다.
모든 문서는 AI에 의해 자동 생성되며, CC BY-SA 4.0 라이선스에 따라 이용할 수 있습니다.
하지만, 위키백과나 뉴스 기사 자체에 오류, 부정확한 정보, 또는 가짜 뉴스가 포함될 수 있으며, AI는 이러한 내용을 완벽하게 걸러내지 못할 수 있습니다.
따라서 제공되는 정보에 일부 오류나 편향이 있을 수 있으므로, 중요한 정보는 반드시 다른 출처를 통해 교차 검증하시기 바랍니다.
문의하기 : help@durumis.com