PHPDOC Verbosity가 가치보다 더 많은 문제가 있습니까? [닫은

Question

나는 오늘 처음으로 PHPDOC를 사용해 보았고 빠르게 문제를 일으켰습니다.

변수 선언의 1 행마다 적어도 5 줄의 댓글이있었습니다. 예시:

/**
 * Holds path the remote server
 * @name ...
 * @global ...
 */
 $myvar = ...

물론 보상은 좋지만 10 라인 구성 파일을 60 라인 파일로 바꿉니다. 나를 영원히 채우고, 나는 그것이 단순한 원 라이너보다 훨씬 더 많은 것을 추가한다고 확신하지 못한다.

또한 내 워크 플로에서 꼬임을 던집니다. 스위프를 변경해야 할 때까지 모두 괜찮고 좋습니다. 잘 문서화 된 문서 블록을 사용하면 갑자기 갑자기 코드를 리팩토링 할 필요가 없지만이 지루한 세부 사항을 모두 다시 작성해야합니다. 당신이 말하는 끝까지 기다려? 하야! 그러면 문서는 결코 일어나지 않을 것입니다.

또한 내 코드 중간에 C 스타일 / ** / 댓글을 강요합니다. 이것은 요구에 따라 큰 블록을 언급 할 수있는 능력을 강화하기 때문에 개발 중에 나를 미치게 만듭니다. 이제 큰 코드 블록을 언급하려면 다음과 같은 것을 가져와야합니다. range, s/^/#/; 그런 다음 나중에 취소하십시오. 성가신!

Long Story Short- PHPDOC를 좋아합니다. 잘 문서화 된 코드를 좋아하지만 한 줄의 코드마다 5 줄의 주석이 있습니다. 너무 많이!. 내가 놓친 기능이 있습니까? 이것이 일반적인 문제입니까?

Answer 1

과잉 여부는 응용 프로그램의 의도 된 사용에 크게 달라집니다. 단일 회사 나 그룹에서만 사용되는 앱을 작성하는 경우 모든 단일 변수에 대한 철저한 문서가 필요하지 않을 수 있습니다.

예를 들어, 지금 당장 저는 상당히 광범위한 코드 기반이지만 개발자가 거의없는 프로젝트를 진행하고 있습니다 (지금은 저만). 클래스와 방법의 두 가지에 대해 PHPDOC 블록을 추가하고 있습니다. 다른 모든 것에 대해, 나는 자주 댓글을 달지 만 PHPDOC 형식은 아닙니다. 이 코드의 대부분은 3-4 명만 볼 수 있으며, 필요한 정보는 블랙 박스 정보입니다. 그들은 개인 클래스 변수가 아닌 모델에서 데이터를 얻는 방법을 알고 싶어합니다.

다른 개발자 나 회사에 배포하려는 앱을 작성하고 앱을 다른 시스템과 통합하거나 기능을 확장 할 것으로 예상하면보다 광범위한 PHPDOC 사용에 더 많은 가치를 부여 할 것입니다. 이러한 종류의 세부 사항은 장기 유지 보수 중에 분명히 유용 할 수 있습니다.

예를 들어, 현재의 프로젝트는 어느 시점에서 다른 사이트에서 API를 작성해야합니다. API는 코드 라인보다 더 많은 주석과 서면 문서가 있다고 확신 할 수 있습니다.