엄격한 타이핑을 사용할 때 docblock typehints가 중복되어 있습니까?

나는 지금 약 10 년 동안 진화 한 꽤 큰 개인 코드베이스를 가지고 있습니다. 나는 phpDocumentor를 사용하지 않지만 오픈 소스 프로젝트에서 docblock 섹션을 사용하는 것이 표준이되었으므로 저장소의 모든 공용 메소드에 docblock을 작성하는 것을 채택했습니다. 대부분의 블록에는 모든 매개 변수와 반환 유형에 대한 작은 설명과 타입 힌트가 포함되어 있습니다.

정적 분석이 시작되면서 이러한 유형 힌트를 통해 불일치와 가능한 버그를 찾는 데 많은 도움이되었습니다. 최근 PHP 코드를 사용하여 가능한 한 모든 매개 변수와 반환 값을 입력 할 수 있도록 전체 코드베이스 (현재 PHP7.2에서 실행 중)를 변환했습니다. 그리고 지금 궁금합니다 ...이 docblock typehints가 중복되지 않습니까? 모든 문서 블록이 끊임없이 변화하는 코드와 동기화되도록 많은 작업을 요구하며 새로운 정보를 추가하지 않기 때문에 완전히 제거하는 것이 더 좋은지 궁금합니다.

한 편으로, 중복 된 문서라도 문서를 제거하는 것은 좋지 않습니다. 다른 한편으로는, 나는 이미 힌팅 된 Do-Not-Repeat-Yourself-principle 일상적인 타입 힌팅을 깨뜨리는 느낌이 듭니다.

코드에서 찾을 수있는 정보는 주석에 중복되지 않아야합니다.

기껏해야 동기화를 유지하기 위해 노력을 낭비하고 있습니다. 아마도 그들은 결국 동기화되지 않을 것입니다. 그 시점에서 그들은 혼란스러워합니다.

정적으로 유형이 지정된 언어 (예 : Java, C #)의 DocBlock과 동등한 내용을 보면 문서 주석에 유형 정보가 포함되어 있지 않습니다. 이것이 PHP 코드에 해당하는 한, 소송을 따르는 것이 좋습니다. 물론 타입 힌트를 적용 할 수없는 경우에도 여전히 주석이 최선의 대안입니다.

이것은 PHP와 관련이 없지만, 유형이 암시 적으로 유추 될 때 중복 된 유형 정보가 의미가있을 수 있습니다 (예 : Haskell).

예, docblock은 PHP 7에서 중복되었습니다.

코딩에서 대부분의 시간은 읽는 데 소비되므로 동일한 내용을 두 번 읽으면 생산성에 영향을줍니다. 또한 실제로 중요한 의견을 쉽게 놓칠 수 있습니다.

특정 유형 (예 : @return int[]또는 @param SomeStatus[] $statusList) 의 배열을 힌트로 입력 하거나 메소드, 매개 변수 또는 반환 값에 대한 주석을 추가하려는 경우를 제외하고는 더 이상 docblock을 쓰지 않습니다 . docblock이 있으면 docblock에 alle 매개 변수와 반환 유형이 없을 때 트리거되는 phpstorm 검사를 비활성화하는 것이 중요하다는 것을 알았습니다.

코드와 문서는 일반적으로 독자가 다릅니다. 문서는 해당 기능의 사용자 를 위한 것 입니다. 유형을 이해하기 위해 코드를 볼 필요는 없습니다. 따라서 문서에는 유형을 포함하여 필요한 모든 정보가 포함되어야합니다.

일부 시스템에서는 코드에서 유형을 가져올 수 있으므로 설명서에서 매개 변수 유형을 지정할 필요가 없습니다. PHPDoc은 그런 시스템이 아닙니다. 대신, @param태그가되고 문서화 된 것을

제공된 경우 예상되는 것을 나타내는 유형을 포함해야합니다.

PHPDoc은 코드 타입 힌트와 비교하여 문서 타입 힌트를 검사하기 때문에 "모든 docblock이 계속 변화하는 코드와 동기화되도록하는 약간의 작업"이 다소 줄어 듭니다. 이것은 일종의 린트 / 정적 분석이므로 문서 생성을 자동화 된 테스트 파이프 라인의 일부로 만듭니다.

스스로 물어보고 싶을 수도있는 또 다른 질문은 이러한 기능이 "변경"할 때 이러한 세부 사항이 자세히 설명되어있는 이유입니다. 일반적인 동기는 인터페이스의 HTML 참조 매뉴얼을 작성하는 것입니다. 그러나 문서를 IDE 외부에서 읽지 않거나 문서가 적합한 안정적인 인터페이스가 없으면 자세한 문서 블록이 필요하지 않거나 오도 될 수 있습니다. 안정된 디자인에 도달 할 때까지 요약 만 작성하고 전체 문서를 연기하는 것이 좋습니다.