코딩스쿨

PHP Comments

PHP 주석: 코드 설명 및 관리에 유용한 주석 사용법

PHP 주석이란?

주석은 PHP 코드 내에서 실행되지 않는 텍스트로, 코드의 특정 부분을 설명하거나 개발자들 간의 의사소통을 돕기 위해 사용됩니다. 주석은 프로그램의 로직에 영향을 미치지 않으며, 유지보수나 디버깅 시 매우 유용합니다. 주석을 적절히 활용하면 코드의 가독성이 높아지고, 나중에 코드를 수정하거나 다른 개발자가 코드를 이해하는 데 큰 도움이 됩니다.

PHP에서는 단일 행 주석과 여러 행 주석의 두 가지 유형이 있습니다.

1. 단일 행 주석 (Single-line Comments)

단일 행 주석은 한 줄의 주석을 작성할 때 사용되며, 두 가지 형식이 있습니다: // 또는 #.

1.1 `//`를 사용한 단일 행 주석

<?php
  // 이 코드는 "Hello, World!"를 출력합니다.
  echo "Hello, World!";
?>

위 코드에서 // 뒤에 있는 내용은 주석으로 간주되어 실행되지 않습니다.

1.2 `#`을 사용한 단일 행 주석

<?php
  # 이 코드도 주석 처리된 내용입니다.
  echo "PHP 주석 사용 예제";
?>

PHP에서는 #을 사용하여 단일 행 주석을 작성할 수도 있습니다. 이는 주로 유닉스 쉘 스크립트 스타일 주석으로 사용됩니다.

2. 여러 행 주석 (Multi-line Comments)

여러 줄에 걸쳐 주석을 작성할 때는 /* */ 구문을 사용합니다. 이 형식은 여러 줄의 설명을 작성하거나 긴 내용을 기록할 때 유용합니다.

2.1 여러 행 주석 예시

<?php
  /*
   이 코드는 두 숫자의 합을 계산합니다.
   변수 $a와 $b는 각각 5와 10으로 설정되어 있습니다.
   결과는 $result 변수에 저장됩니다.
  */
  $a = 5;
  $b = 10;
  $result = $a + $b;

  echo $result; // 15 출력
?>

이 예시에서 /* */ 사이의 모든 내용은 주석으로 처리되며, 실행되지 않습니다. 여러 줄에 걸쳐 작성된 주석은 긴 설명이나 코드의 특정 부분을 명확하게 표현하는 데 유용합니다.

3. 주석을 사용하는 이유

3.1 코드 가독성 향상

주석을 통해 코드의 목적이나 동작 방식을 명확하게 설명할 수 있습니다. 예를 들어, 복잡한 알고리즘이나 로직이 있는 경우 주석으로 보충 설명을 해두면 나중에 다시 코드를 볼 때 이해하기 쉬워집니다.

<?php
  // 사용자로부터 입력된 나이를 검사하여 성인인지 확인합니다.
  $age = 20;

  if ($age >= 18) {
    echo "성인입니다."; // 18세 이상일 경우 성인으로 처리
  } else {
    echo "미성년자입니다."; // 18세 미만일 경우 미성년자로 처리
  }
?>

3.2 코드 유지보수 및 디버깅 용이

주석은 코드 유지보수에 큰 도움이 됩니다. 팀 프로젝트나 오랜 시간 후에 코드를 수정할 때, 주석이 있으면 코드의 흐름이나 변수, 함수의 역할을 쉽게 파악할 수 있습니다.


  // 다음 코드는 아직 미완성된 기능입니다.
  // $result = performComplexCalculation();
?>

이처럼 주석으로 나중에 개발할 부분이나 미완성된 기능을 표시해 두면, 작업 진행 중 놓친 부분을 다시 찾기 쉬워집니다.

4. PHPDoc 스타일 주석

PHPDoc은 함수, 클래스, 변수 등을 설명하기 위해 사용되는 표준화된 주석 형식입니다. 이를 통해 코드 자동 문서화를 할 수 있으며, 특히 객체 지향 프로그래밍(OOP)에서 유용합니다.

4.1 PHPDoc 주석 예시


  /**
   * 두 숫자의 합을 계산하는 함수입니다.
   *
   * @param int $a 첫 번째 숫자
   * @param int $b 두 번째 숫자
   * @return int 두 숫자의 합
   */
  function add($a, $b) {
    return $a + $b;
  }

  echo add(5, 10);  // 15 출력
?>

@param: 함수에 전달되는 인수의 타입과 설명을 나타냅니다.
@return: 함수의 반환 값에 대한 설명을 포함합니다.

이와 같은 주석 스타일은 IDE(통합 개발 환경)에서 함수의 설명을 자동으로 표시해 주거나, 코드를 문서화할 때 유용하게 사용됩니다.

5. 주석 작성 시 유의할 점

주석을 너무 많이 사용하지 않기: 모든 코드에 주석을 다는 것은 가독성을 해칠 수 있습니다. 코드 자체가 명확하면 불필요한 주석은 피하는 것이 좋습니다.
주석의 내용이 최신 상태인지 확인하기: 코드가 업데이트될 때 주석도 함께 업데이트해야 합니다. 주석과 코드가 불일치하면 혼란을 초래할 수 있습니다.
명확하고 간결하게 작성: 주석은 짧고 간결하게 작성하되, 코드의 중요한 부분에 대해서는 충분한 설명을 달아야 합니다.

6. 요약

PHP 주석은 코드의 가독성 및 유지보수를 돕는 중요한 요소입니다. 단일 행 주석과 여러 행 주석을 적절히 사용하여 코드의 동작을 설명하고, PHPDoc 스타일을 통해 함수나 클래스에 대한 문서를 자동화할 수 있습니다. 주석을 잘 활용하면 코드의 품질과 이해도를 크게 향상시킬 수 있습니다.

코딩 스쿨 PHP