Ferramentas de Usuário

Ferramentas de Site


dev_net:vb.net:sumarios

Sumários - O BI dos nossos métodos e propriedades

Introdução

Quando escrevemos código, principalmente quando escrevemos bibliotecas, temos de estar conscientes que não as estamos a escrever apenas para nós mesmos. É correcto afirmar que à partida ninguém consegue seguir imediatamente a nossa linha de raciocínio e por vezes nem nós mesmos a conseguimos apanhar ao fim de alguns meses. Comentar o código é importante e ajuda a entender o raciocínio que se desenvolveu na altura mas muito melhor do que isso, e de uma forma muito mais organizada (já para não falar integrada no IDE) temos os sumários.

Aplicar um sumário

É muito simples aplicar um sumário. Ou o escrevemos todo ou utilizamos o código que é gerado quando se escrevem três pelicas ( ' ). Antes de um método ou propriedade, na linha imediatamente acima, escreva três pelicas. Deverá obter uma estructura de tags, semelhante ao conhecido XML. Seguem-se alguns exemplos:

    ''' <summary>
    ''' 
    ''' </summary>
    ''' <remarks></remarks>
    Public Sub AtirarPedrasAoCao()
 
    End Sub
 
    ''' <summary>
    ''' 
    ''' </summary>
    ''' <param name="TipoDeComida"></param>
    ''' <remarks></remarks>
    Public Sub DarDeComerAoGato(ByVal TipoDeComida As String)
 
    End Sub
 
    ''' <summary>
    ''' 
    ''' </summary>
    ''' <param name="AnimalDeEstimacao"></param>
    ''' <param name="UsarPinca"></param>
    ''' <returns></returns>
    ''' <remarks></remarks>
    Public Function ContarPulgas(ByVal AnimalDeEstimacao As String, ByVal UsarPinca As Boolean) As Integer
 
    End Function

Observe-se a forma como o código gerado se adapta ao tipo de método que está a sumariar. Onde existem argumentos, o tag "param" é criado. Se o método ostentar um tipo de devolução, o tag "returns" é criado. Todos estes tags servem para armazenar informação.

O que significa o quê?

TagDescrição
<summary></summary> Entre estes tags escrevemos a descrição do método. No fundo o que ele vai fazer ou qualquer outro tipo de informação que sirva para o descrever.
<param name="nome_do_parametro"> </param> Entre estes tags escrevemos a descrição do argumento, ou parâmetro. No fundo o que ele significa, qual a sua função exacta dentro do método ou outro tipo de informação que sirva para o descrever.
<returns></returns> Entre estes tags escrevemos o que este método é suposto devolver e/ou situações excepcionais de devolução ou outro tipo de informação que sirva para descrever o que é devolvido.
<remarks></remarks> Se existe alguma informação adicional, acerca do método, que devemos ter em conta, é entre estes tags que deve ser colocada.

Onde posso consultar a informação?

Para além de ser uma forma de comentário muito mais organizada, o seu formato XML não é em vão. Este código é utilizado para preencher a informação adicional dos métodos no "Object Browser", mas mais interessante ainda, são os textos que aparecem em "tooltip auxiliar" quando abrimos os parenteses para introduzir argumentos ou parâmetros.

Returns e Remarks são visíveis apenas a partir do "Object Browser"

O exemplo, completo

    ''' <summary>
    ''' Atirar o máximo número de pedras possíveis ao cão.
    ''' </summary>
    ''' <remarks>Atiram-se pedras porque o desgraçado voltou a roubar a chouriça.</remarks>
    Public Sub AtirarPedrasAoCao()
 
    End Sub
 
    ''' <summary>
    ''' Dar de comer ao gato que está esfomeado.
    ''' </summary>
    ''' <param name="TipoDeComida">Tipo de comida que vamos dar ao gato.</param>
    ''' <remarks>Convém não dar chouriça ao gato pois o cão já a comeu.</remarks>
    Public Sub DarDeComerAoGato(ByVal TipoDeComida As String)
 
    End Sub
 
    ''' <summary>
    ''' Conta todas as pulgas do animal de estimação.
    ''' </summary>
    ''' <param name="AnimalDeEstimacao">Animal de estimação onde contar as pulgas.</param>
    ''' <param name="UsarPinca">Determina se devemos usar uma pinça para auxiliar a contagem.</param>
    ''' <returns>Integer com o número de pulgas resultante da contagem.</returns>
    ''' <remarks>Antes de contar as pulgas ao cão, convém atirar-lhe as pedras.</remarks>
    Public Function ContarPulgas(ByVal AnimalDeEstimacao As String, ByVal UsarPinca As Boolean) As Integer
 
    End Function

Conclusão

As novas ferramentas possuem poderes fantásticos e é o nosso dever procurar saber utilizar tudo aquilo que nos possa vir a fazer perder menos tempo. Se comentar é importante, sumariar torna-se fulcral.

dev_net/vb.net/sumarios.txt · Última modificação em: 2018/05/14 21:37 (edição externa)