Fala galera, beleza? Esse blog aqui ja ta parado a muito tempo, se você quer mais conteúdo tech basta ir para https://tuliocalil.com.br/ .
Olá! Eu corrigi, atualizei e adicionei mais conteúdo nesse post e postei ele no DEV.TO, acesse ele aqui!
Por mais que temos uma documentação para o nosso projeto, é bem comum sentirmos a necessidade de documentar alguns trechos do código, explicando o que ta acontecendo ali ou explicar o que uma determinada função faz, o que ela espera e o que ela devolve. Tudo bem que com Typescript isso não é tão "problemático" assim, IDEs e editores de código como o Visual Studio Code utilizam a tipagem que fazemos como informação quando utilizamos/chamamos um método/objeto "tipado", isso ajuda bastante, porém, isso não é possível no Javascript, e mesmo no Typescript, você pode sentir a necessidade de explicar mais sobre aquela função ou mesmo dar um exemplo. Sendo assim, vamos ver um pouco sobre comentários em Javascripts (e claro, você pode usar para outras linguagens, modificando pouca ou nenhuma coisa da syntax).
Índice
- Introdução
- Tipos de comentário
- Comentário em linha
- Comentário em bloco
- Comentário de bloco descritivo
- Um pouco mais
- Considerações finais
Introdução
Comentários no código é algo que alguns desenvolvedores vêm como algo ruim: "se precisa ser explicado, o código não está tão bom assim", "variáveis e funções descritivas são melhores do que blocos de código". E existem os que defendem os comentários, com argumentos como "Você não precisa analisar toda uma função para saber o que ela faz", "existe trechos complexos que mesmo código descritivo não resolve".
Eu acredito que existem situações e situações, como tudo na tecnologia/vida, um framework/linguagem pode ser a melhor escolha pra um problema X, assim como comentar ou não o código pode ser a melhor escolha pro projeto Y.
Sendo assim, me deparei com um projeto onde apesar de trabalhar sozinho(inicialmente), ficará um bom tempo rodando na empresa, e por isso decidi comentar, tanto para dar a previa dos argumentos de funções, quanto descreva-las o mais simples possível, pensando justamente em futuros devs que vão manter o projeto.
Sendo assim, vou mostrar aqui algumas boas praticas e dicas, além de mostrar alguns tipos de comentários para cada etapa do seu código.
Tipos de comentário
Temos dois principais tipos ou estilos de comentários, e cada um serve bem pra certo momento do código, podemos optar por algo mais simples, em uma unica linha ou algo com mais linhas e bem mais informativo, que pode até passar informações como autor, parâmetros etc.
Comentário em linha
Comentários em linha são o tipo mais simples, e presente em quase todas as linguagens de programação, consiste em basicamente iniciarmos um comentário na mesma linha ou na linha acima/abaixo do código que queremos falar sobre, no Javascript, utilizados duas barras "//" para tal:
Utilizei um comentário em linha para descrever o que a função "numerosMaiorQue" faz, dessa forma, outro dev vai ficar mais descritivo (mesmo o nome da função já ser bem intuitiva e a função ser simples, mas é só um exemplo).
Comentário em bloco
Outra opção são os comentários em blocos, que consistem em um comentário que inicia e fecha em um intervalo de linhas, caso você queira escrever muito, é a melhor opção:
Dessa forma, abrimos o comentário com '/*' na primeira linha e fechamos mais abaixo com '*/', podendo escrever livremente nesse intervalo, tendo quebra de linhas etc.
E se quisermos melhorar ainda mais esse comentário, é possível ? SIM!
Comentário de bloco descritivo
Uma das opções que mais gosto de usar e que fica muito bom para outros devs, principalmente quando estamos trabalhando com Javascript, são os comentários de bloco descritivo, onde podemos passar algumas propriedades no comentário o qual a nossa IDE vai interpretar e nos mostrar quando formos usar um método, por exemplo:
Desta forma, deixamos bem claro qual a descrição da nossa função, quais argumentos ela recebe e o que ela retorna, e se você usar uma IDE ou editor de código que dê suporte a esse tipo de comentário(Visual Studio Code, por exemplo), vai ter um resultado similar a esse quando chamar essa função:
Ainda apodemos melhorar um pouco mais ? SIM!
Podemos ver que conseguimos "tipar" os argumentos e o retorno, porém, ele esta retornando "any" em alguns casos, podemos melhorar isso usando o conceito de Generics do Typescript:
Basicamente, o que fizemos aqui foi adicionar o tipo dos itens do array, dizendo que é um array de números (Array<Number>), dessa forma, não teremos mais a IDE exibindo "any[]", e conseguimos documentar ainda mais nosso código:
Um pouco mais
Até aqui nosso comentário já esta bem legal e explicativo, mas vamos supor que tenhamos outra função, que recebe um objeto, e queremos "tipar" esse objeto, como podemos fazer isso ? Simples:
Nesse exemplo temos uma função que recebe um objeto (já estou desestruturando para que fique mais claro, e também ajuda no intellisense da IDE) de usuário com varias propriedades, então no nosso comentário, basta dizer qual o nome do objeto e o tipo, nesse caso é um object e o nome usuário e em seguida vamos "tipar" as propriedades que estão dentro do objeto usuário, que são: nome, sobrenome, idade e sexo, temos como resultado:
E da pra fazer isso em classes ? SIM!
Vamos imagina que tenhamos uma classe para gerenciar o usuário e que temos um método nela para gerar um id aleatório para o usuário, então vamos documentar tanto a classe quanto esse método, ficando dessa forma:
E com isso, temos esse resultado:
Considerações finais
Esse post foi para mostrar alguns cases e tentar ajudar quem esta na duvida sobre comentar ou não o código e até mesmo como comentar, deixei o post mais detalhado e intuitivo possível, espero que tenham gostado, compartilhe esse post no seu Linkedin, Twitter ou Facebook e até a próxima!
Links interessantes:
Extensão do Visual Studio Code para melhorar as anotações de comentário: Better Coments.
Comentários em linha no código oficial do Nodejs.
Comentários
Postar um comentário