Olá digionautas!
Estou de volta com mais um artigo da minha jornada no Bootcamp Everis Kotlin Developers. E quero dizer que está sendo um verdadeiro desafio. Principalmente agora, que cheguei ao módulo 7: "Fundamentos de Orientação a Objetos com Kotlin". Bem, como o título já diz, quero compartilhar com vocês sobre como começar a realizar comentários e gerar uma mini-documentação no próprio código.
Primeiro seguem as vantagens. Ter na sua classe, comentários sobre os parâmetros, propriedades e o que faz cada trecho do seu código é de extrema importância e mostra o nível de organização de todo programador. Trechos bagunçados são difíceis de serem avaliados. Principalmente o digionauta que me lê e está passando por uma avaliação nos seus estudos para um estágio ou vaga de emprego. Bem, se vocês verem alguma desvantagem é só comentar abaixo.
Na documentação oficial do Kotlin aqui, é possível perceber a semelhança com o sistema de documentação do Java, o JavaDoc. Mas temos uma simplicidade maior quando se trata do KDoc, como o uso do markdown, por exemplo. No noss caso vamos nos ater ao básico.
Usamos os caracteres "/**" + Enter para escrever um comentário longo. No início de uma classe e acima de todo o código, por exemplo, descrevemos organizadamente o nosso código com a descrição do que faz essa classe. Ou um comentário simplista apenas, como no exemplo da documentação:
/**
* A group of *members*.
*
* This class has no useful logic; it's just a documentation example.
*
* @param T the type of a member in this group.
* @property name the name of this group.
* @constructor Creates an empty group.
*/
class Group<T>(val name: String) {
/**
* Adds a [member] to this group.
* @return the new size of the group.
*/
fun add(member: T): Int { ... }
}
Hipoteticamente, o exemplo traz na primeira frase, um título da classe. Na segunda sentença, o que esta classe faz. De forma fácil após o /** a sua IDE geralmente irá completar com o fechamento */ numa nova linha e entenderá que ali você iniciou um novo comentário. Cada Enter corresponde automaticamente a uma nova linha de comentário (mantenha tudo organizado e espaçado).
Então, existem três tipos de comentário importantíssimos que foram iniciados com o caracter "@", que faz parte da sintaxe do sistema de comentários de sua IDE. Eu utilizo o IntellliJ IDEA 2020.3 que já vem por padrão a biblioteca do KDoc que entenderá a atribuição específica do comentário:
@param <name> - Se sua classe tem um parâmetro, especifique-o em uma nova linha, substituindo o <name> pelo nome do seu parâmetro case sentitive. Após isso, você poderá explicar que parâmetro esse ou deixar uma mensagem curta na mesma linha
@property <name> - novamente, substitua o <name> pelo nome da propriedade da sua classe. Linha por linha cada atributo ou, encadeando na mesma linha como na linguagem que você está programando, como iterar o atributo. Exemplo: [Pessoa.nome], [Pessoa.numero] Para saber mais sobre esse encadeamento consulte a documentação ao final do artigo.
@constructor - comente sobre o uso de um construtor primário ou secundário
Estamos quase no fim, relaxa! Falta falarmos sobre como comentar funções dentro de nossa classe. Bem, muito fácil. É só uma linha acima da função você abrir um novo espaço e setar um novo comentário /** + Enter e então dizer para que serve sua função, descrever como ensinei acima quais parâmetros ela espera receber e o tipo de retorno em uma nova linha com @return e descrever na mesma linha que tipo de retorno será aguardado.
Não esqueçamos que para cada ação, poderemos usar comentários simples com um "//" e descrever resumidamente o que determinado trecho de código, por exemplo, realiza.
Para se aprofundar e tirar dúvidas sugiro a documentação oficial:
https://kotlinlang.org/docs/kotlin-doc.html?q=it#kdoc-syntax
Exemplo de código comentado com KDoc
Comentários (0)