나는 최고의 코딩 관행을 유지하려고 노력하고 있으며 웹 애플리케이션을 작성하는 동안 PHP에 대한 PEAR 코딩 표준을 따르고 있습니다. 필자는 코드를 작성하는 동안 나를 안내하기 위해 phpcs 를 사용 하고 있지만 PHP 클래스에 대한 클래스 문서뿐만 아니라 파일 문서도 포함 시키라 는 요청 을 받고 있습니다.
모든 클래스 파일은 각 파일의 맨 위에 "파일 수준"docblock과 각 클래스 바로 위에 "클래스 수준"docblock을 포함해야합니다. 이러한 docblock의 예는 아래에서 찾을 수 있습니다.
파일 문서
/**
* Short description for file
*
* Long description for file (if any)...
*
* LICENSE: Some license information
*
* @category Zend
* @package Zend_Magic
* @subpackage Wand
* @copyright Copyright (c) 2005-2014 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license BSD License
* @version $Id:$
* @link http://framework.zend.com/package/PackageName
* @since File available since Release 1.5.0
*/
수업 문서
/**
* Short description for class
*
* Long description for class (if any)...
*
* @category Zend
* @package Zend_Magic
* @subpackage Wand
* @copyright Copyright (c) 2005-2014 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license BSD License
* @version Release: @package_version@
* @link http://framework.zend.com/package/PackageName
* @since Class available since Release 1.5.0
* @deprecated Class deprecated in Release 2.0.0
*/
두 문서는 형식과 주석이 너무 가깝기 때문에 동일한 클래스 파일에 두 문서가 모두 필요한지 궁금합니다. 특히 PHP 파일 당 하나의 클래스를 구현할 때 문서 수준과 클래스 수준의 설명은 동일합니다. 이런 종류의 문서와 관련하여 현재 PHP 커뮤니티 내에서 잘 확립되고 존경받는 표준과 보편적 관행은 무엇입니까?
코딩 표준은 클래스 정의가있는 파일이 하나의 클래스 만 포함하고 다른 것은 포함하지 않도록 요구하는 방향으로 이동했습니다. 그래서, 경우 이 한 클래스 당 파일 요구 사항이 존재, 다음은 파일 docblock 앤 클래스 docblock 느낌의 중복을 만들기 위해 보인다. 그러나 CS 요구 사항을 초과하는 것은 파일에 다른 항목이있는 것을 방해하지 않으므로 파일 자체를 문서화 할 방법이 여전히 필요합니다.
생성 된 문서에는 일반적으로 클래스뿐만 아니라 파일 자체에 대한 문서가 있습니다. 파일 docblock은 문서 페이지에 표시 할 내용을 제어하는 방법입니다. docblock 클래스에있는 내용을 복제하려는 경우 선택 사항이지만 필수는 아닙니다.
이 파일에 상수 만 정의되어 있고 자체 docblock이 필요하다면이 파일에 대해이 대화를 나눌 수 있습니다. :-)
이 기사는 인터넷에서 수집됩니다. 재 인쇄 할 때 출처를 알려주십시오.
침해가 발생한 경우 연락 주시기 바랍니다[email protected] 삭제
몇 마디 만하겠습니다