As dicas de tipo docblock são redundantes ao usar a digitação estrita

Eu tenho uma base de código privada bastante grande que evoluiu por cerca de dez anos. Não estou usando o phpDocumentor, mas como o uso das seções docblock se tornou o padrão em projetos de código aberto, adotei a escrita de docblocks para todos os métodos públicos no meu repositório. A maioria dos blocos contém apenas uma pequena descrição e dicas de tipo para todos os parâmetros e o tipo de retorno.

Com a chegada da análise estática, essas dicas de tipo me ajudaram bastante a encontrar inconsistências e possíveis erros. Ultimamente eu converti toda a base de código (agora rodando no PHP7.2) para ter todos os parâmetros e retornar valores com dicas de tipo sempre que possível, usando as dicas de tipo do PHP. E agora eu estou pensando ... Essas dicas de tipo de docblock não são redundantes? Ele exige bastante trabalho para manter todos os docblocks em sincronia com o código em constante mudança e, como eles não adicionam nenhuma informação nova, fico imaginando se é melhor removê-los completamente ou não.

Por um lado, remover a documentação é ruim, mesmo quando é redundante. No outro, eu realmente sinto vontade de quebrar o princípio diário de não digitar coisas que já está com dicas.

As informações que podem ser encontradas no código não devem ser duplicadas nos comentários.

Na melhor das hipóteses, é um esforço desperdiçado para mantê-los sincronizados. Provavelmente, eles ficarão fora de sincronia eventualmente. Nesse ponto, eles são apenas confusos.

Se você observar o equivalente ao DocBlock em linguagens estaticamente tipadas (por exemplo, Java, C #), verá que os comentários do documento não contêm informações de tipo. Na medida em que este for o caso no seu código PHP, eu recomendo fortemente que sigam o exemplo. Obviamente, onde dicas de tipo não podem ser aplicadas, um comentário ainda é sua melhor alternativa.

Isso não é relevante para o PHP, mas informações duplicadas do tipo podem fazer sentido quando o tipo é implicitamente inferido (por exemplo, Haskell).

Sim, os docblocks se tornaram redundantes com o php 7.

A maior parte do tempo na codificação é gasta lendo, portanto, ter que ler a mesma coisa duas vezes afeta sua produtividade. Além disso, facilita a falta de comentários realmente importantes.

Não escrevo mais docblocks, exceto quando quero digitar uma matriz de um determinado tipo (por exemplo, @return int[]ou @param SomeStatus[] $statusList) ou quando quero adicionar um comentário sobre o método, parâmetros ou valor de retorno. Achei importante desabilitar a inspeção do phpstorm que é acionada quando você não tem todos os parâmetros e retorna tipos em um docblock se você tiver um docblock.

O código e a documentação geralmente têm públicos diferentes: a documentação é para usuários dessa função. Eles não deveriam ter que olhar o código para entender os tipos. Portanto, a documentação deve incluir todas as informações necessárias, incluindo os tipos.

Em alguns sistemas, não é necessário especificar um tipo de parâmetro na documentação porque o tipo pode ser obtido do código. O PHPDoc não é esse sistema. Em vez disso, a @paramtag está documentada que

Quando fornecido, DEVE conter um tipo para indicar o que é esperado

O “bastante trabalho para manter todos os docblocks sincronizados com o código em constante mudança” é um pouco reduzido, porque o PHPDoc verificará as dicas de tipo de documentação em relação às dicas de tipo de código. Esse é um tipo de análise de fiapos / estática, portanto, faça da geração de sua documentação parte do seu pipeline de teste automatizado.

Outra pergunta que você pode querer perguntar é por que essas funções são documentadas nesses detalhes quando estão “sempre mudando”. A motivação usual é criar um manual de referência HTML de suas interfaces. Porém, se a documentação nunca for lida fora de um IDE, ou se você não tiver interfaces estáveis ​​nas quais a documentação faça sentido, os blocos de documentos detalhados serão desnecessários ou até enganosos. Pode ser melhor escrever apenas um resumo e adiar documentos completos até chegar a um design estável.