|
Usuários |
|
78 Usuários Online
|
|
[Artigos]
[Básico] - Documentando seus códigos no Delphi |
Publicado por rboaro : Terça, Março 19, 2013 - 10:04 GMT-3 (960 leituras)
 9 Comentários  Enviar para um amigo  Versão para impressão
|
Definitivamente eu não gosto de comentários em código. Pode parecer não fazer sentido o que estou dizendo, mas comentários são venenos que colaboram para a deterioração de um código fonte. Qual é a unica razão para criar um comentário? Seja realista com você mesmo e responda com sinceridade. Tenho certeza que algo la no fundo está dizendo, “colocamos comentários quando o código não está suficientemente claro”, isso é péssimo, optar por criar um comentário no lugar de refatorar o código para que esse seja claro, é uma triste derrota. Como não estou escrevendo isto para despejar criticas sobre o uso de comentários, vamos falar sobre o assunto principal do post, o uso de documentações do Delphi, o XML Documentation.
Diferente de você escrever um comentário, documentar métodos e classes com o XML Documentation, dentro de suas limitações ainda sim é muito mais útil. Mas do que estamos realmente falando? Com certeza você já viu algo assim quando estava codificando:
Isso se chama Help Insight. Desta forma como está apresentado não ajuda muito, você não concorda comigo que seria muito melhor se fosse assim?
Principalmente se estamos falando de uma API onde os fontes não são disponibilizados, eu não tenho duvidas que a segunda forma é muito melhor. Mas como podemos fazer isso ? Através de comentários (ok, voltamos nesse assunto) iniciados com três barras (///), devidamente formatados e com tags xml especiais. Por exemplo, como fizemos com o método demonstrado acima:
/// <summary>Método que realiza o processamento principal dos arquivos de movimentos mensais gerando o agrupamento central</summary>
/// <param name="ACaminho">Caminho do arquivo de parametrização da geração do agrupamento central</param>
/// <returns>True se o processamento foi ok e False para possíveis exceções</returns>
/// <remarks>Em caso de falha verificar os arquivos de log</remarks>
/// <exception cref="EIOErro">Caso o arquivo de referencia não exista</exception>
/// <exception cref="EProcErro">Caso falhe o processamento</exception>
function RealizarProcessamentoCentral(const ACaminho : string):boolean;
A documentação é feita sempre acima do método/classe/record e caso contenha alguma falha de sintaxe a descrição não irá ser apresentada. As principais tags utilizadas são seguintes:
<summary>: Uma breve descrição sobre o proposito do método
<param name=”NomeDoParametro>: Uma descrição sobre um determinado parâmetro, identificado pelo seu nome dentro da tag xml.
<returns>: Uma descrição sobre o retorno do método, particularmente útil quando um método pode voltar determinados códigos de falha ou sucesso.
<remarks>: Uma possível observação sobre o método.
<exception cref=”NomeDaExceção”>: Referencia e observação a uma possível exceção na execução do método.
A lista completa pode ser encontrada em http://docwiki.embarcadero.com/RADStudio/XE3/en/XML_Documentation_Comments. Para visualizar a documentação de um método/classe/record, basta pressionar Ctrl + Shit + H em cima de uma chamada ou declaração desses. Para usa o recurso de exporta a documentação do projetos (através do model view) essas tag são utilizadas como referência para montar essa documentação.
Assim como os comentários, este tipo de documentação também é falha, pois não acompanha a evolução do código, ou seja, caso neste exemplo eu remova o parâmetro ACaminho a documentação não irá espelhar essa alteração fazendo com o que a documentação esteja defasada e mais atrapalhe do que ajude. Portanto, eu sugiro que use esse recurso com cautela e tenha a consciência de manter sua documentação atualizada caso passe a usar. Mesmo assim, nada substitui um código limpo e claro.
|
|
 Comentários | |
| | Comentários pertencem aos seus respectivos autores. Não somos responsáveis pelo seus conteúdos. |
por: michael_jackson (capitaocaverna007@hotmail.com)
: Mar 22, 2013 - 08:21
(Informações sobre o membro | Enviar uma mensagem)
|
|
pra mim comentário serve para a seguinte ocasião, as vezes vocês está trabalhando todo dia no mesmo software, então você conhece de cabo a rabo o código fonte, mas se você fica meses sem contato com ele, você acaba se esquecendo de como funciona o código fonte, qual era a sequência, o que era executado primeiro, o que era depois, etc... e os comentários ajudam avocê se lembrar.
|
por: drgarcia1986 (drgarcia1986@gmail.com) : Mar 28, 2013 - 09:43
(Informações sobre o membro | Enviar uma mensagem) http://drgarcia1986.wordpress.com | | eu Michael, eu não concordo com isso, para mim o código precisa estar claro não só para a pessoa que está desenvolvendo mas para qualquer um que precisar dar manutenção no código. Eu sou a favor da posse coletiva do código em uma empresa, aonde qualquer um pode mexer em um código fonte caso seja necessário, mas para isso, sem um código claro e limpo, seria impossível. Criar comentários para melhorar a legibilidade do código (coisa que na minha opinião o código já deveria fazer por si só) é criar uma dependência que com certeza com o passar do tempo só iria atrapalhar (principalmente quando o código evolui e o comentário não). É claro, essa é uma questão de opinião |
[ Comentários não permitidos para usuários anônimos. Por gentileza, registre-se ou conecte-se ao sistema
por: marcosweimer (marcosweimer@gmail.com)
: Mar 27, 2013 - 03:30
(Informações sobre o membro | Enviar uma mensagem)
|
A partir de qual versão do delphi este recurso está presente? Costumo utilizar no C# quando digito /// antes da declaração o C# já gera automaticamente as chaves.
Com certeza é muito útil, valeu pela dica. (Nem sonhava que isso era possível no delphi)
|
|
|
Edição 112 |
|
|
50 Programas Fontes |
|
|
Produtos |
|
|
