Comentários no código (Visual Basic)
À medida que você lê os exemplos de código, você encontra geralmente o símbolo de comentário ('). Esse símbolo diz para o compilador do Visual Basic ignorar o texto ou o comentário que o segue. Os comentários são uma breve explicação e/ou anotações adicionadas ao código para o benefício de quem os lê.
É uma prática de programação recomendável iniciar todos os procedimentos com um breve comentário descrevendo as características do procedimento e sua funcionalidade (o que ele faz). Isso é um benefício para o programador e é vantajoso para qualquer pessoa que examinar o código. Você deve separar os detalhes de implementação (como o procedimento faz isso) dos comentários que descrevem as características funcionais. Quando você incluir detalhes da implementação na descrição, lembre-se de atualizá-los quando você atualizar a função.
Comentários podem seguir uma instrução na mesma linha ou ocupar uma linha inteira. Ambos são ilustrados no código a seguir.
' This is a comment beginning at the left edge of the screen.
text1.Text = "Hi!" ' This is an inline comment.
Se seu comentário exigir mais de uma linha, use o símbolo de comentário em cada linha, como o exemplo a seguir mostra.
' This comment is too long to fit on a single line, so we break
' it into two lines. Some comments might need three or more lines.
Diretrizes de comentários
A tabela a seguir fornece diretrizes gerais para os tipos de comentários que podem preceder uma seção de código. São sugestões; o Visual Basic não impõe regras para adicionar comentários. Escreva o que funciona melhor, tanto para você quanto para qualquer outra pessoa que leia seu código.
Tipo de comentário |
Descrição do comentário |
Finalidade |
Descreve o que o procedimento faz (não como ele faz) |
Suposições |
Lista cada variável externa, controle, arquivo aberto ou outro elemento acessado pelo procedimento |
Efeitos |
Listas cada variável externa, controle ou arquivo afetado, e o efeito que ele tem (somente se não for óbvio) |
Entradas |
Especifica a finalidade do argumento |
Retorna |
Explica os valores retornados pelo procedimento |
Lembre-se dos seguintes pontos:
Cada declaração de variável importante deve ser precedida por um comentário sobre o uso da variável sendo declarada.
Variáveis, controles e procedimentos devem ser chamados claramente o bastante para que os comentários sejam necessários somente para detalhes de implementação complexos.
Os comentários não podem seguir uma sequência de continuação de linha na mesma linha.
Você pode adicionar ou remover símbolos de comentário de um bloco de código selecionando uma ou mais linhas de código e escolhendo os botões Comentar (.gif "VisualBasicWinAppCodeEditorCommentButton")
) e Remover comentário (.gif "VisualStudioWinAppProjectUncommentButton")
) na barra de ferramentas Editar.
Dica
Você também pode adicionar comentários ao código precedendo o texto com a palavra-chave REM.No entanto, o símbolo ' e os botões Comentar/Remover comentário são mais fáceis de usar e exigem menos espaço e memória.
Consulte também
Tarefas
Como criar documentação XML no Visual Basic
Referência
Marcas XML recomendadas para comentários da documentação (Visual Basic)