PHPDoc verbosidade é mais problema do que vale a pena? [fechadas]

Question

Eu tentei usar PHPDoc pela primeira vez hoje e rapidamente correu para um problema.

Para cada 1 linha de declarações de variáveis, eu tinha pelo menos 5 linhas de comentários. Exemplo:

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

É claro que as recompensas são nice - mas isso vira um arquivo de configuração de 10 linhas em um arquivo de 60-line. me leva uma eternidade para preencher, e eu ainda não estou convencido de que acrescenta que muito mais de um one-liner simples.

Ele também lança uma torção no meu trabalho. Tudo está bem e bom até que eu preciso fazer mudanças radicais. Com meus doc-blocos bem documentados, de repente, eu já não tenho refatorar meu código, mas eu preciso re-escrever todos esses detalhes tediosos. Espere até o final você diz? HAH! Em seguida, a documentação nunca vai acontecer.

Em cima de tudo isso - isso me força em estilo C / ** / comentários no meio do meu código. Este me deixa louco durante o desenvolvimento, uma vez que retira a capacidade de comentar grandes blocos sob demanda. Agora para comentar a um grande bloco de código, eu preciso puxar algo como: gama, s / ^ / # /; em seguida, desfazer-la mais tarde. ! Irritante

Para encurtar a história - I como PHPDoc, eu adoro bem documentado código - mas 5 linhas de comentários para cada uma linha de código é demasiado !. Existem características que eu estou ausente? É este um problema comum?

Answer 1

Se é ou não é um exagero depende muito do uso pretendido para a sua aplicação. Se você estiver escrevendo um aplicativo que será usado apenas por uma única empresa ou grupo, você provavelmente não precisa de documentação exaustiva de cada variável única.

Por exemplo, agora eu estou trabalhando em um projeto com uma bastante extensa base de código, mas muito poucos desenvolvedores (por enquanto, apenas me). Eu estou adicionando blocos PHPDoc por duas coisas: classes e métodos. Para tudo o resto, eu comentar com frequência, mas não em formato PHPDoc detalhado. A maior parte deste código só vai ser visto por três ou quatro pessoas, e as informações que eles vão necessidade é preto caixa de informação: o que eu enviar para este método, o que eu esperar para sair dela. Eles querem saber como obter dados a partir de um modelo, não o que uma variável de classe privada é para.

Se eu estivesse escrevendo um app que eu pretendia distribuir para outros desenvolvedores ou empresas, e eu esperava que eles se integrem meu aplicativo com outros sistemas ou estender sua funcionalidade, eu iria colocar mais valor em uso mais extensivo PHPDoc. Esse tipo de detalhe definitivamente poderia vir a calhar durante a manutenção a longo prazo.

O caso em questão, o meu projeto atual, em algum momento exige a criação de uma API para ser acessado a partir de outros sites. Você pode apostar que API terá mais comentários e documentação escrita de linhas de código.