[SP-pm] Documentação de cabeçalho de rotinas

Lucas F. Rosada lucasrosada em gmail.com
Sexta Janeiro 11 09:30:45 PST 2008


Otávio,

Quando disse "documentar as funções e manter o POD do script em geral (com
sinópse, autor, etc.) sem se ater às funções", eu estava me referindo a
fazer um comentário com "#" no cabeçalho da função, explicando seus detalhes
(para o desenvolvedor) e no POD (no fim do script) documentar estritamente o
uso do script.
Quanto a isso, inclusive, há um comentário no perlmonks no qual o usuário
defende esse mecanismo de comentário acima (além de também questionar sobre
a poluição visual que o POD Inline provoca). Acredito, sim, que a
documentação deve ser completa e auto-explicativa, dispensando (na maior
medida possível) a leitura do código-fonte.

Agora, retomando uma das perguntas: existe algum padrão que vocês usam para
documentar as rotinas?
Existe algum modo bem difundido de documentação diferente do POD, que polua
menos o script e permita, por exemplo, gerar man pages dos comentários?

Desde já fico grato pelas respostas.

Lucas.

On Jan 11, 2008 1:34 PM, Otávio Fernandes <otaviof em gmail.com> wrote:

> Lucas,
>
> Nao deveria ser ao contrario ?!
>
> A leitura de um fonte para saber o que o script faz eh errado, pois
> consome muito mais tempo, e consequentemente, uma manutencao de rotina
> tambem vai consumir. O ideal eh que somente com a documentacao do
> script, no comeco de cada funcao e do arquivo, te deem toda a
> informacao do que o script faz, e como ele o faz. O comentario vai ser
> muito util na hora de alterar uma rotina, porem o excesso dele, no meu
> ponto de vista, atrapalha.
>
> um abraco,
>
> --
>  | --
>  | Otávio Fernandes < otaviof | gmail | com >
>  | FreeBSD 7.0-PRERELEASE && GNU/Linux User: 283.396
>  | (( Especial Programação )) http://geekbr.podcastbrasil.com/ -- 0.15
>  | --
>  _______________________________________________
> SaoPaulo-pm mailing list
> SaoPaulo-pm em pm.org
> http://mail.pm.org/mailman/listinfo/saopaulo-pm
>



-- 
"O que há aí para mim?"
-------------- Próxima Parte ----------
Um anexo em HTML foi limpo...
URL: http://mail.pm.org/pipermail/saopaulo-pm/attachments/20080111/cf6c4a3b/attachment-0001.html 


Mais detalhes sobre a lista de discussão SaoPaulo-pm