"이 코드는 왜 썼지?" PHP 주석으로 깔끔하게 소통하는 법

1. PHP 주석의 종류와 올바른 활용법

PHP는 목적에 따라 세 가지 주석 방식을 제공합니다. 이를 명확히 구분하는 것이 협업의 첫걸음입니다.

• 싱글 라인 주석 (//): 코드 한 줄의 의도를 짤막하게 설명할 때 사용합니다.

• 멀티 라인 주석 (/* */): 여러 줄의 설명이 필요하거나, 복잡한 로직의 시작점에서 전체적인 흐름을 요약할 때 적합합니다.

• PHPDoc/DocBlock (/** */): 클래스, 메서드, 함수 상단에 작성하며, IDE(PHPStorm 등)에서 타입 힌팅과 자동 완성을 제공하는 표준 방식입니다.

💡 시니어 Pro Tip: HTML 주석의 위험성 PHP 코드 블록(<?php ... ?>) 안에서 실수로 <!-- -->와 같은 HTML 주석을 사용하지 마세요. PHP 엔진은 이를 주석으로 인식하지 못해 **구문 에러(Parse Error)**를 발생시키거나 사용자 화면에 불필요한 코드를 노출합니다. 주석은 반드시 해당 언어의 문법에 맞춰야 합니다.

--------------------------------------------------------------------------------

2. '좋은 주석' vs '나쁜 주석' (Clean Code 원칙)

클린 코드의 관점에서 주석은 '필요악'입니다. 가장 좋은 것은 주석 없이도 이해되는 코드지만, 실무의 복잡한 알고리즘이나 비즈니스 맥락에서는 주석이 빛을 발합니다.

좋은 주석: 정보와 의도를 담는다

• 결정의 이유 설명: '어떻게'가 아닌 '왜(Why)' 그렇게 짰는지를 설명해야 합니다.

• 복잡한 알고리즘 요약: 세부 로직을 뜯어보기 전에 전체 흐름을 이해할 수 있는 징검다리를 놓아주세요.

• TODO / FIXME: 미완성된 기능이나 긴급히 수정이 필요한 곳을 명시하여 추적 가능하게 합니다.

• 법적 정보 및 제약 사항: 저작권 정보나 특정 환경에서의 경고(예: "이 함수는 음수 값을 처리하지 못함")를 기재합니다.

[코드 예시: 복잡한 알고리즘 요약 (에라토스테네스의 체)]

/**
 * 에라토스테네스의 체 알고리즘을 사용하여 소수 목록을 구함
 */
public function findPrimes(int $limit): array {
    $isPrime = array_fill(0, $limit + 1, true);
    $isPrime[0] = $isPrime[1] = false;

    for ($i = 2; $i * $i <= $limit; $i++) {
        // 소수가 아닌 배수들을 걸러냄
        if ($isPrime[$i]) {
            for ($j = $i * $i; $j <= $limit; $j += $i) {
                $isPrime[$j] = false;
            }
        }
    }
    // ... 이하 결과 반환 로직
}

나쁜 주석: 소음과 오해를 낳는다

• 코드 반복: $i++; // i를 1 증가시킴과 같은 주석은 가독성을 해치는 쓰레기 데이터입니다.

• 낡은 주석: 코드는 수정됐는데 주석은 그대로라면, **"틀린 주석은 주석이 없는 것보다 훨씬 더 비싼 비용(버그)을 치르게 한다"**는 사실을 명심하세요.

• 메타데이터: 저자 이름이나 수정 날짜는 Git(VCS) 히스토리에서 확인하면 충분합니다.

• 시각적 공해: 과도한 배너 장식(/////////////////)은 오히려 중요한 정보를 가립니다.

--------------------------------------------------------------------------------

3. 최고의 주석은 '주석이 필요 없는 코드'

주석을 달기 전, 리팩토링으로 의도를 드러낼 수 없는지 먼저 고민해야 합니다.

이름만 잘 지어도 주석은 사라집니다

모호한 함수 시그니처를 직관적인 이름으로 바꾸는 것만으로도 수많은 @param 설명을 줄일 수 있습니다.

// 나쁜 예: 주석 없이는 의미 파악이 힘듦
/** @return bool */
public function check($img, $w, $h) { ... }

// 좋은 예: 자기 설명적 코드(Self-documenting Code)
public function hasLegalDimensions($base64_image, $legal_width, $legal_height): bool { ... }

현대적인 PHP 타입 선언 활용

PHP 7/8 이후 도입된 타입 선언을 적극 활용하세요. int $width라고 타입을 명시했다면, PHPDoc에 @param int $width라고 중복 기재할 필요가 없습니다. 시니어는 이런 **시각적 노이즈(Redundancy)**를 제거하여 코드의 밀도를 높입니다. 또한, 예외가 발생하는 경우 @throws를 명시하여 다음 작업자가 대비할 수 있게 하세요.

--------------------------------------------------------------------------------

4. 실무에서 빛을 발하는 시니어의 주석 전략

"왜"를 설명하는 주석의 힘

특이한 버그 수정이나 비즈니스 요구사항 때문에 "이상해 보이는" 코드를 짜야 할 때가 있습니다. 이때 주석의 진가가 드러납니다.

// ✅ 부동 소수점 연산에서 -0.0이 출력되는 특이 케이스 방지 (부호 정리)
// 왜 이 로직이 필요한지 설명하지 않으면, 다음 작업자가 리팩토링 중 삭제할 위험이 있음.
$result = ($result == -0.0) ? 0.0 : $result;

티켓 번호와 마이그레이션 가이드

비즈니스 로직 변경 시 Jira나 GitHub의 티켓 번호를 주석에 남기세요. 티켓 시스템이 바뀌더라도, 당시의 결정 맥락을 추적할 수 있는 유일한 단서가 됩니다.

또한, 레거시 코드를 개선할 때 기존 함수를 바로 지우지 말고 @deprecated를 활용하세요.

/**
 * @deprecated v2.1.0 이후 사용 중단. 대신 newServiceMethod()를 사용하세요.
 * @link https://jira.company.com/browse/DEV-123
 */
public function oldLegacyMethod() {
    return $this->newServiceMethod();
}

--------------------------------------------------------------------------------

5. 도구와 AI의 도움 받기

기술 전문가는 도구를 영리하게 활용합니다.

1. phpDocumentor: 프로젝트 전체의 PHPDoc을 분석해 웹 형태의 API 문서를 자동 생성해줍니다. 공개 라이브러리를 개발한다면 필수입니다.

2. IDE 활용: PHPStorm 등에서 주석과 타입 선언이 일치하지 않을 때 주는 경고를 무시하지 마세요. 주석은 IDE가 버그를 찾아내는 훌륭한 데이터셋입니다.

3. AI(Readable 등) 활용: 일관된 주석 형식을 유지하는 데 도움을 줍니다. 단, AI는 '어떻게(How)'는 잘 설명하지만 **비즈니스 의도인 '왜(Why)'**는 알지 못합니다. AI가 생성한 주석을 반드시 개발자의 시각으로 검토하십시오.