정의 및 사용 방법

PHP 주석(Comments)은
PHP 영역에 설명 메모를 추가하거나, PHP 엔진이 코드의 특정 부분을 해석하거나 실행하지 못하도록 무효화하는 데 사용됩니다.

올바른 이해와 사용 방법에 대해 알아봅니다.

PHP 주석 작성 형식

PHP에는 '한 줄 주석'과 '여러 줄 주석' 형식이 있습니다.

PHP에는 주석을 작성하기 위한 두 가지 형식이 있습니다.
한 줄로만 주석을 작성할 수 있는 '한 줄 주석'과 한 줄 또는 여러 줄에 걸쳐 주석을 작성할 수 있는 '여러 줄 주석'입니다.

PHP의 주석을 작성하기 위한 두 가지 형식의 주석
형식개요
한 줄 주석 한 줄로만 주석을 간단하게 작성할 때 사용합니다.
// 기호 또는 # 기호 뒤에 작성하며, 해당 줄의 끝까지 주석 처리됩니다. 줄바꿈을 허용하지 않습니다.
여러 줄 주석 한 줄 또는 여러 줄로 된 주석을 모두 작성할 수 있습니다.
/* 기호로 시작하고 */ 기호로 끝나는 구간은 모두 주석 처리됩니다. 구간 사이에는 필요시 가독성을 위해 줄바꿈을 할 수 있습니다.

한 줄 주석

'한 줄 주석'은 두 개의 슬래시(// 기호) 또는 해시(# 기호)로 시작하며, 기호부터 해당 줄의 끝까지 주석 처리됩니다. 줄바꿈을 허용하지 않습니다.

PHP 
// 한 줄 주석입니다.
$x = 1; // 이것도 한 줄 주석입니다.

# 이것도 PHP에서 사용할 수 있는 한 줄 주석입니다.
$y = 2; # 주로 쉘 스크립트나 파이썬 스타일을 선호할 때 사용합니다.
HTML과 함께 작성한 PHP 
<h1>이것은 <?php // echo '간단한 '; ?>예제입니다.</h1>
<p>위의 제목은 화면에 '이것은 예제입니다.'라고 표시됩니다.</p>
HTML과 함께 작성한 PHP 
<h1>이것은 <?php # echo '간단한 '; ?>예제입니다.</h1>
<p>위의 제목은 화면에 '이것은 예제입니다.'라고 표시됩니다.</p>

참고하세요!
'한 줄 주석'으로는 주로 // 기호를 많이 사용하는 편입니다.
하지만, 쉘 스크립트나 파이썬 스타일을 선호할 때에는 # 기호를 사용하는 경우도 있습니다.

일반적으로 가독성을 위해 // 기호 또는 # 기호 다음에 한 칸을 띄어서 주석의 내용을 작성합니다.

여러 줄 주석

'여러 줄 주석'은 /* 기호로 시작하고 */ 기호로 끝납니다. 이 구간 사이는 주석 처리됩니다.
구간 사이에 줄바꿈을 허용하기 때문에 필요시 가독성을 위해 줄바꿈을 한 주석을 작성할 때 유용합니다.

보통은 '한 줄 주석'과 구분하기 위해 '여러 줄 주석'이라고 말하지만, 한 줄 또는 여러 줄로 된 주석을 모두 작성할 수 있는 특징이 있습니다.

PHP 
/* 한 줄로 작성한 여러 줄 주석입니다. */
$x = 1; /* 이것도 한 줄로 작성한 여러 줄 주석입니다. */

/* 이런 형식도
   가독성을 위한 여러 줄 주석입니다. */

/*
이런 형식도
여러 줄 주석입니다.
*/
HTML과 함께 작성한 PHP 
<h1>이것은 <?php /* echo '간단한 '; */ ?>예제입니다.</h1>
<p>위의 제목은 화면에 '이것은 예제입니다.'라고 표시됩니다.</p>

코드를 실행하지 않도록 주석으로 무효화하기

'한 줄 주석'이나 '여러 줄 주석'은 모두 설명 메모를 추가하기 위해 사용됩니다.
주석으로 처리된 내용은 PHP 엔진이 해석하거나 실행하지 못하도록 무효화하기 때문에, 이러한 원리를 이용해 코드의 특정 부분을 일부러 주석으로 처리하는 경우가 있습니다. 코드의 특정 부분을 삭제하지 않고 주석으로 실행만 막기 위한 경우입니다.

이러한 경우는 개발할 때 매우 자주 쓰는 유용한 방법입니다. 주요 이유는 다음과 같습니다.

임시 디버깅 및 에러 추적

  • 원인 분석: 특정 코드 줄에서 에러가 날 때, 그 부분만 주석으로 막고 실행해 보며 원인을 찾기 위해 주석으로 처리합니다.
  • 격리 테스트: 문제가 되는 기능을 잠시 격리하여 나머지 코드가 정상 작동하는지 확인하기 위해 주석으로 처리합니다.

이전 코드의 보존 및 비교

  • 백업 효과: 코드를 완전히 지웠다가 나중에 다시 필요해지면 복구하기 어렵기 때문에 주석으로 처리해 잠시 남겨둡니다.
  • 로직 비교: 기존 방식과 새로 수정 중인 방식을 화면에 동시에 띄워두고 비교해가며 개발할 수 있습니다.

기능 개발 및 배포 제어

  • 기능 보류: 개발은 끝났지만 아직 사용자에게 공개하면 안 되는 미완성 기능을 잠시 숨겨둘 때 씁니다.
  • 환경별 제어: 개발 환경(로컬 PC)에서만 실행하고 실제 운영 서버에서는 실행하면 안 되는 코드를 제어합니다.

작업 메모

나중에 구현해야 하거나 수정이 필요한 코드를 주석으로 적어두어 나침반 역할을 하게 합니다.

PHP 
// 내일 출근해서 이 부분 성능 개선하기

$x = 10;
// $y = 20;  // 에러가 의심되어 잠시 실행을 막아둔 코드 (무효화)
$z = 30;

// echo "여기까지는 잘 작동함";

주의할 점

주석은 매우 유용한 도구이지만, 잘못 사용하면 코드에 에러가 발생하거나 오히려 가독성을 해칠 수 있습니다. 주석을 작성할 때는 다음 두 가지 사항을 반드시 주의해야 합니다.

/* 기호로 시작하는 여러 줄 주석은 반드시 */ 기호로 닫아야 합니다.

여러 줄 주석을 시작하는 /* 기호는 PHP 엔진에게 "지금부터 주석 시작이야"라고 알려주는 신호입니다. 만약 주석이 끝나는 부분에 */ 기호를 빼먹으면, 그 아래에 있는 모든 실제 코드까지 전부 주석으로 처리되어 작성한 코드가 작동하지 않습니다.

PHP 
/* 여러 줄 주석을 시작합니다.
   깜빡하고 닫는 기호를 작성하지 않으면...

$x = 10; // 닫는 기호가 없어서 이 코드까지 모두 무효화됩니다!
$y = 20;

과도한 주석은 오히려 가독성을 떨어뜨립니다.

주석은 코드를 설명하는 보조 도구일 뿐입니다. 코드 한 줄마다 모두 주석을 달거나, 누구나 보면 다 아는 당연한 내용까지 과도하게 주석을 적으면 오히려 실제 코드를 읽는 데 방해가 됩니다.

주석이 없어도 코드 그 자체로 무엇을 하는지 쉽게 이해할 수 있도록 명확한 코드를 짜는 것이 먼저이며, 주석은 꼭 필요한 핵심 설명이나 복잡한 로직을 설명할 때만 선별적으로 사용하는 것이 좋습니다.

PHP - 아쉬운 예: 너무 당연한 내용까지 주석을 달아 코드가 지저분해짐 
$age = 20; // age 변수에 20을 대입함
$age = $age + 1; // age에 1을 더함
PHP - 좋은 예: 복잡하거나 중요한 의도가 담긴 부분에만 주석을 작성함 
$discount_rate = 0.1; // 만 19세 미만 미성년자에게 적용할 10% 할인율

참고문헌

같이 보기