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 estrutura 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ê?

Tag	Descrição
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	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	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	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 parênteses para introduzir argumentos ou parâmetros.

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

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.