절차 코드에서 DocBlock 주석을 사용하는 방법이 더 효과적입니까?

Question

절차적인 PHP 스타일로 스크립트를 작성하고 있지만 최선의 모든 것을 문서화하고 싶습니다. DocBlock 주석을 사용하는 이유.

/** 
* Checks string length 
* 
* @param int $max_length an integer determining the string length to check against 
* @param string $string the string to be checked 
* @return bool a boolean value indicating if the string is shorter or longer 
*    than $max_length. True if shorter, false if longer 
*/ 
function check_length($max_length = 2, $string) { 
    $i = 0; 

    if(strlen($string) > $max_length) 
     return false; 

    return true; 
} 

는 $i가 그 기능을 위해 필요하다 가정하자 : 그들에게 새로운이기 때문에, 나는 다음과 같은 시나리오 (이 질문에 대해 특별히 작성된 코드)에서 사용하는 방법을 생각해 본다. 어떻게 문서화해야합니까? 인수가 아니기 때문에 DocBlock 함수 안에 넣을 수 없습니다.

example에는 비슷한 클래스가 있지만 객체 지향 코드를 작성하지 않으므로 $i을 함수 외부에 넣을 수 없습니다. 또는 사용할 수 있도록 코딩 스타일을 변경하고 싶지 않습니다. DocBlocks).

또 다른 접근법은 함수를 사용하기 때문에 중요하지 않으므로 이러한 '내부'변수를 문서화하지 않는 것입니다.

Answer 1

PHP-Doc-Comments는 모듈/클래스/기타의 API 문서로 볼 수 있습니다. $ i는 코드의 사용자에게 흥미가 없기 때문에 API 문서에 넣을 이유가 무엇입니까? 사용자는 그것에 대해 알 필요가 없으므로 사용자에게 알릴 필요가 없습니다. $ 나는 실제로 코드를 읽거나 검토하는 사람에게 흥미로울 수 있습니다. 따라서 $ i가 무엇인지 설명하는 간단한 한 줄 주석 (//)이나 필요한 경우 여러 줄 주석을 추가해야합니다.