Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Post artigo #13

Merged
merged 1 commit into from
Nov 27, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 133 additions & 0 deletions jsdocs-artigo.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
---
author: Pedro Simões ( @pedrodev )
pubDatetime: 2024-11-23T00:00:00.000Z
modDatetime: 2024-11-23T00:00:00.000Z
title: JsDocs - Documentação melhorada para seu código!
slug: jsdocs-1
featured: false
draft: false
tags:
- dicas
- javascript
- typescript
- jsdocs
description: JsDocs é uma forma de adicionar tipagem ao seu código, JavaScript, o que não é possível sem ele.
---

### **JSDoc: Tipagem para JavaScript**

Se você já trabalhou em um projeto JavaScript ou TypeScript por um tempo, sabe o quanto o código pode ficar complexo e difícil de entender. Um dos maiores desafios para desenvolvedores, especialmente em equipes, é manter a clareza do código. A documentação tradicional nem sempre está atualizada ou é detalhada o suficiente. É aí que entra o **JSDoc**: uma ferramenta poderosa para documentar diretamente no código, tornando o processo de desenvolvimento muito mais organizado e eficiente.

---

### **O que é o JSDoc e como ele funciona?**

O JSDoc é um padrão de comentários que permite documentar a lógica do seu código usando tags especiais em comentários multi-linha. Ele transforma esses comentários em documentação compreensível e estruturada. Com isso, o código se torna autoexplicativo e facilita muito a vida de quem precisa entender ou manter a aplicação.

JSDoc não é apenas útil para gerar documentação visual — ele também melhora a experiência de codificação nos editores, fornecendo autocompletar e validações adicionais. Ele é como um superpoder para o desenvolvimento!

---

### **Vantagens do JSDoc**

#### 📘 **1. Documentação sempre atualizada**
A maior vantagem do JSDoc é que a documentação está integrada diretamente no código. Se você fizer alterações na lógica ou nos parâmetros, basta atualizar os comentários. Isso evita discrepâncias entre a documentação escrita separadamente e o código real.

#### 🧑‍💻 **2. Melhora a comunicação entre desenvolvedores**
Se você está trabalhando em equipe, explicações claras sobre funções, classes e métodos são essenciais. O JSDoc permite que qualquer pessoa entenda rapidamente o propósito de cada parte do código, mesmo sem contexto prévio. Isso torna o processo de onboarding de novos membros mais fácil e eficiente.

#### ⚡ **3. Suporte avançado em IDEs e editores**
Editores modernos como o **Visual Studio Code** oferecem suporte nativo ao JSDoc. Ao passar o cursor sobre uma função ou variável, você pode ver a documentação, incluindo descrições dos parâmetros e tipos de retorno. Isso reduz a necessidade de consultar arquivos externos ou documentação online.

#### 🔄 **4. Tipagem para JavaScript**
Embora o JavaScript seja uma linguagem dinâmica, o JSDoc permite simular um sistema de tipos semelhante ao TypeScript. Isso ajuda a evitar erros comuns, fornecendo informações sobre os tipos esperados e retornados pelas funções.

---

### **Como usar JSDoc na prática?**

JSDoc usa um padrão de comentários de bloco (`/** ... */`). Dentro desse bloco, você pode usar tags específicas para descrever diferentes aspectos do seu código. Vamos ver algumas das tags mais comuns:

#### **Descrição básica de uma função**
```javascript
/**
* Calcula o quadrado de um número.
* @param {number} x - O número a ser elevado ao quadrado.
* @returns {number} O quadrado de x.
*/
function quadrado(x) {
return x * x;
}
```

#### **Documentando parâmetros opcionais e padrões**
```javascript
/**
* Concatena(liga) duas strings.
* @param {string} str1 - A primeira string.
* @param {string} [str2=''] - A segunda string (opcional).
* @returns {string} - Fala que ele retorna uma string.
*/
function liguar(str1, str2 = '') {
return str1 + str2;
}
```

#### **Documentando classes e métodos**
```javascript
/**
* Representa uma pessoa.
* @class
*/
class Pessoa {
/**
* Cria uma instância de Pessoa.
* @param {string} nome - O nome da pessoa.
* @param {number} idade - A idade da pessoa.
*/
constructor(nome, idade) {
this.nome = nome;
this.idade = idade;
}

/**
* Retorna a saudação da pessoa.
* @returns {string} A saudação.
*/
cumprimentar() {
return `Olá, meu nome é ${this.nome} e tenho ${this.idade} anos.`;
}
}
```

---

### **Tags úteis no JSDoc**

Aqui estão algumas tags essenciais para documentação com JSDoc:

- `@param {tipo} nome` — Documenta um parâmetro da função.
- `@returns {tipo}` — Descreve o valor de retorno de uma função.
- `@example` — Fornece exemplos de uso do código.
- `@deprecated` — Indica que um método ou função não deve mais ser utilizado.
- `@see` — Adiciona referências para documentação relacionada.
- `@throws` — Documenta as exceções que a função pode lançar.
- `@async` — Indica que a função é assíncrona.

---

### **Benefícios específicos para TypeScript**

Embora o TypeScript já ofereça suporte a tipagem estática, o JSDoc ainda é útil:

1. **Documentação pública:** Facilita a criação de documentação visual para APIs públicas.
2. **Compatibilidade com JS:** Em projetos mistos (JS + TS), o JSDoc pode ajudar na transição gradual para TypeScript.
3. **Tipagem extra:** Adiciona mais contexto sobre tipos complexos, ajudando a manter o código TypeScript ainda mais compreensível.

---

### **Conclusão: Invista na documentação!**

Se você deseja manter um código organizado, compreensível e escalável, o JSDoc é uma ferramenta essencial. Ele não apenas ajuda na documentação, mas também melhora sua produtividade ao escrever código e facilita a colaboração com outros desenvolvedores.

Então, da próxima vez que escrever uma função ou classe, não deixe de incluir comentários JSDoc. Seu código e sua equipe agradecem! 🚀