<div>Otávio,</div>
<div> </div>
<div>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.
</div>
<div>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.
</div>
<div> </div>
<div>Agora, retomando uma das perguntas: existe algum padrão que vocês usam para documentar as rotinas?</div>
<div>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?</div>
<div> </div>
<div>Desde já fico grato pelas respostas.</div>
<div> </div>
<div>Lucas.<br><br></div>
<div class="gmail_quote">On Jan 11, 2008 1:34 PM, Otávio Fernandes <<a href="mailto:otaviof@gmail.com">otaviof@gmail.com</a>> wrote:<br>
<blockquote class="gmail_quote" style="PADDING-LEFT: 1ex; MARGIN: 0px 0px 0px 0.8ex; BORDER-LEFT: #ccc 1px solid">Lucas,<br><br>Nao deveria ser ao contrario ?!<br><br>A leitura de um fonte para saber o que o script faz eh errado, pois
<br>consome muito mais tempo, e consequentemente, uma manutencao de rotina<br>tambem vai consumir. O ideal eh que somente com a documentacao do<br>script, no comeco de cada funcao e do arquivo, te deem toda a<br>informacao do que o script faz, e como ele o faz. O comentario vai ser
<br>muito util na hora de alterar uma rotina, porem o excesso dele, no meu<br>ponto de vista, atrapalha.<br><br>um abraco,<br><font color="#888888"><br>--<br> | --<br> | Otávio Fernandes < otaviof | gmail | com ><br>
| FreeBSD 7.0-PRERELEASE && GNU/Linux User: 283.396<br> | (( Especial Programação )) <a href="http://geekbr.podcastbrasil.com/" target="_blank">http://geekbr.podcastbrasil.com/</a> -- 0.15<br> | --<br></font>
<div>
<div></div>
<div class="Wj3C7c">_______________________________________________<br>SaoPaulo-pm mailing list<br><a href="mailto:SaoPaulo-pm@pm.org">SaoPaulo-pm@pm.org</a><br><a href="http://mail.pm.org/mailman/listinfo/saopaulo-pm" target="_blank">
http://mail.pm.org/mailman/listinfo/saopaulo-pm</a><br></div></div></blockquote></div><br><br clear="all"><br>-- <br>"O que há aí para mim?"