코드 주석 (Comment)

코드 주석(Comment)은 소스 코드 안에 설명이나 메모를 남기도록 프로그래밍 언어가 구분해 놓은 부분입니다. 일반 주석의 내용은 계산이나 함수 호출처럼 실행할 문장으로 처리되지 않습니다. 코드의 의도와 조건을 설명하는 데 쓰며, 시작과 끝을 나타내는 기호는 언어마다 다릅니다. 일부 주석은 파일 해석이나 도구가 읽는 지시 역할도 합니다.

설명을 남기는 위치와 주석 기호

MDN의 JavaScript 어휘 문법은 코드에 설명이나 주의 사항을 더하는 용도로 주석을 소개합니다. JavaScript에서 //는 그 뒤부터 같은 줄의 끝까지를 주석으로 만듭니다. /*와 */로 감싸는 블록 주석은 한 줄 안에도 쓸 수 있고 여러 줄에 걸쳐 쓸 수도 있습니다. 주석 내용과 실제 실행할 코드의 경계는 이런 문법으로 정해집니다.

‘수량에 가격을 곱한다’처럼 바로 아래 계산을 그대로 읽어 주는 설명보다, 특정 조건을 둔 이유를 적으면 코드만으로 알기 어려운 맥락을 보탤 수 있습니다. 임시 처리라면 어떤 상황에서 필요한지와 관련 결정을 남기는 식입니다. 주석은 실행되는 계산을 대신하지 않으므로, 주석에 적은 의도와 실제 계산이 맞는지는 코드를 함께 읽어 확인합니다. 설명이 자세해도 코드가 그 설명대로 동작한다는 증거가 되지는 않습니다.

Python의 주석 문법은 문자열에 속하지 않는 #에서 시작해 물리적인 줄 끝까지를 주석으로 정의합니다. 주석만 한 줄에 두거나 코드 뒤에 짧게 붙일 수 있습니다. 같은 기호라도 따옴표 안의 문자열에 들어 있으면 문자열의 일부입니다. 색상 값을 표현하는 문자열의 #나 주소 문자열의 //를 보고 이후 내용이 주석이라고 판단하면 실제 값을 잘못 읽게 됩니다.

주석 처리와 문서화 문자열의 차이

MDN의 블록 주석 설명은 실행할 코드를 주석 안에 넣어 일시적으로 실행되지 않게 하는 예시도 제시합니다. 로그를 출력하는 호출을 감싸면 그 호출은 실행되지 않습니다. 이를 주석 처리라고 부릅니다. 설명을 덧붙이는 것과 기존 실행문을 주석으로 바꾸는 것은 결과가 다르며, 후자는 실행될 코드를 바꾸는 편집입니다.

주석 처리한 코드가 다시 필요해질 것인지와 그 코드가 올바른지는 별도 판단입니다. 이미 실행하지 않는 큰 코드 덩어리가 남아 있으면, 읽는 사람이 어떤 부분이 실제 프로그램인지 구분하는 데 시간이 듭니다. 문제를 조사하며 잠시 끈 기능이라면 비활성화한 범위와 이유를 확인합니다. 실제 코드가 바뀐 뒤에도 오래된 설명이나 주석 처리된 코드가 남으면, 작업자가 이전 동작을 기준으로 판단할 수 있습니다.

Python의 함수 정의 안내는 함수 본문의 첫 문장에 놓인 문자열 리터럴을 문서화 문자열, 또는 독스트링(docstring)으로 설명합니다. #로 시작하는 일반 주석과 달리 문자열이라는 언어 요소로 작성하며, 문서 도구가 이를 이용해 설명 자료를 만들 수 있습니다. 세 따옴표로 여러 줄을 썼다는 사실만으로 모두 주석이 되지는 않습니다. 문자열이 놓인 위치와 역할을 함께 확인해야 문서화 문자열인지 일반 문자열인지 구분됩니다.

언어와 도구가 해석하는 예외

Python의 인코딩 선언 규칙은 파일 첫째나 둘째 줄의 주석이 정해진 형식에 맞으면 소스 파일의 인코딩 선언으로 처리한다고 명시합니다. 이 선언은 독립된 줄에 있어야 하며, 둘째 줄에 두는 경우 첫째 줄도 주석만 있는 줄이어야 합니다. 일반적인 설명 주석을 읽지 않는다는 문법 규칙을 모든 처리 단계에서 주석을 전혀 보지 않는다는 뜻으로 넓힐 수는 없습니다.

JavaScript에도 파일 맨 처음의 #!로 시작하는 특수 주석이 있습니다. MDN의 해시뱅 주석 설명에 따르면 JavaScript 해석기는 이를 일반 주석처럼 다루지만 셸에서 파일을 직접 실행할 때는 사용할 해석기를 지정하는 의미가 있습니다. 어떤 프로그램이 파일을 읽느냐에 따라 같은 줄의 역할이 달라지는 사례입니다. 형식과 위치가 정해진 특수 주석은 일반 설명문과 구별해 살핍니다.

코드를 수정한 뒤에는 주변 주석의 조건과 이름도 실제 구현에 맞는지 확인합니다. 재시도 횟수를 바꿨는데 주석에 옛 횟수가 남아 있으면 다음 작업자는 코드와 주석에서 서로 다른 횟수를 보게 됩니다. AI가 생성한 주석도 같은 기준으로 읽습니다. 설명의 자연스러움보다 그 설명이 가리키는 함수와 조건이 코드에 존재하는지, 언급한 동작이 실제 처리와 일치하는지가 확인 대상입니다.