JavaScript.

Kanban iterativo

20/01/202516/01/2025 Por antonino

Veremos hoje um Kanban iterativo, criando componentes javascript em tempo de execução no front-end.

Criando componentes em tempo de execução

O Kanban iterativo é uma metodologia ágil amplamente utilizada para gerenciar projetos de forma visual e eficiente. Com sua abordagem intuitiva, ele facilita a organização e acompanhamento de tarefas em diferentes etapas. Recentemente, construí um Kanban digital, o que trouxe uma nova perspectiva sobre como gerenciar atividades e melhorar a produtividade. Neste post, explorarei os principais recursos e a importância dessa ferramenta na minha jornada de desenvolvimento.

Primeiramente, o Kanban digital oferece uma interface prática e fácil de usar. A estrutura da ferramenta permite a criação de grupos (como “Em andamento”, “Concluído” e “A Fazer”) para organizar os itens de trabalho. Cada grupo pode ter múltiplos itens, que representam tarefas específicas. Além disso, o sistema oferece a funcionalidade de “drag-and-drop”, ou arrastar e soltar, permitindo que os itens sejam movidos entre os grupos com facilidade. Com isso, a visualização do progresso do projeto se torna clara e dinâmica.

Outro ponto importante é a possibilidade de personalizar o Kanban conforme as necessidades de cada usuário. Ao adicionar e editar grupos ou itens, é possível ajustar o quadro conforme a evolução do projeto. Para garantir que as informações não se percam, implementei um sistema de salvamento dos dados no cookie do navegador, o que possibilita carregar e recuperar o quadro sempre que necessário, mantendo o histórico de alterações.

Menu flutuante nos objetos

Além disso, a integração de menus contextuais para cada grupo e item proporciona um nível extra de interação. O usuário pode, por exemplo, excluir ou editar itens diretamente no menu de contexto, sem precisar abrir outras interfaces ou se distrair com processos complicados. Dessa forma, as ações tornam-se mais diretas e práticas.

Em termos de usabilidade, o Kanban digital é acessível a qualquer pessoa que precise de uma forma visual e ágil de gerenciar tarefas. A integração de criptografia para salvar os dados no navegador é outra medida que proporciona segurança e confiabilidade ao sistema.

Por fim, a possibilidade de personalizar e salvar os dados em cookies oferece flexibilidade e autonomia ao usuário. Assim, além de ser uma ferramenta eficaz para gerenciamento de tarefas, ela também se torna uma aliada indispensável para quem busca produtividade e organização. Concluindo, o Kanban digital não é apenas uma plataforma de gerenciamento, mas um reflexo da constante busca por aprimoramento nas metodologias ágeis.

Vejamos um exemplo de KanBan que podemos fazer de forma dinâmica abaixo.

JAVASCRIPT:

/**
 * Obtém os elementos do DOM para manipulação posterior
 * @type {HTMLElement}
 */
const addGrupoButton = document.getElementById('add-grupo');
const addItemButton = document.getElementById('add-item');
const nomeNovoGrupoInput = document.getElementById('nome-novo-grupo');
const nomeNovoItemInput = document.getElementById('nome-novo-item');
const kanban = document.getElementById('kanban');
const contextMenu = document.getElementById('contextMenu');
const contextMenuGrupo = document.getElementById('contextMenuGrupo');
const editarItemOption = document.getElementById('editarItem');
const excluirItemOption = document.getElementById('excluirItem');
const editarGrupoOption = document.getElementById('editarGrupo');
const excluirGrupoOption = document.getElementById('excluirGrupo');

let itemCounter = 3; // Começa após o último item existente
let currentItem = null; // Referência ao item atual do menu de contexto
let currentGrupo = null; // Referência ao grupo atual do menu de contexto

/**
 * Função para salvar o estado atual do Kanban no cookie
 * @function
 */
function saveKanbanToCookie() {
  const grupos = [];
  const grupoElements = document.querySelectorAll('.titulo-grupo');

  grupoElements.forEach(grupoElement => {
    const grupo = {
      nome: grupoElement.querySelector('h1').textContent,
      itens: []
    };

    const itemElements = grupoElement.querySelectorAll('.grupo .item');
    itemElements.forEach(item => {
      grupo.itens.push(item.textContent);
    });

    grupos.push(grupo);
  });

  // Converte os dados em JSON
  const jsonData = JSON.stringify(grupos);

  // Criptografa os dados
  const encryptedData = CryptoJS.AES.encrypt(jsonData, 'secret-key').toString();

  // Salva os dados criptografados no cookie
  document.cookie = `kanbanData=${encryptedData}; path=/; max-age=${60 * 60 * 24 * 365}`;
}

/**
 * Função para carregar o Kanban a partir do cookie
 * @function
 */
function loadKanbanFromCookie() {
  const cookies = document.cookie.split('; ');
  const kanbanCookie = cookies.find(cookie => cookie.startsWith('kanbanData='));

  if (kanbanCookie) {
    // Extrai e descriptografa os dados do cookie
    const encryptedData = kanbanCookie.split('=')[1];
    const bytes = CryptoJS.AES.decrypt(encryptedData, 'secret-key');
    const jsonData = bytes.toString(CryptoJS.enc.Utf8);

    // Converte de volta para um objeto
    const kanbanData = JSON.parse(jsonData);

    // Cria os grupos e itens a partir dos dados
    kanbanData.forEach(grupo => {
      createGrupo(grupo.nome); // Cria o grupo
      const grupoElement = document.querySelector(`#kanban .titulo-grupo:last-child .grupo`);
      grupo.itens.forEach(item => {
        createItem(item, grupoElement); // Cria os itens dentro do grupo
      });
    });
  }
}

/**
 * Função para criar um novo grupo
 * @param {string} nome - Nome do grupo a ser criado
 * @function
 */
function createGrupo(nome) {
  const tituloGrupo = document.createElement('div');
  tituloGrupo.className = 'titulo-grupo';

  const grupo = document.createElement('div');
  grupo.className = 'grupo';
  grupo.addEventListener('dragover', handleDragOver);

  const titulo = document.createElement('h1');
  titulo.textContent = nome;
  titulo.addEventListener('contextmenu', handleContextMenuGrupo); // Adicionando o menu de contexto para o título do grupo

  tituloGrupo.appendChild(titulo);
  tituloGrupo.appendChild(grupo);
  kanban.appendChild(tituloGrupo);
}

/**
 * Função para criar um novo item dentro de um grupo
 * @param {string} nome - Nome do item a ser criado
 * @param {HTMLElement} grupo - O grupo onde o item será adicionado
 * @function
 */
function createItem(nome, grupo) {
  const item = document.createElement('div');
  item.className = 'item';
  item.draggable = true;
  item.id = `item-${++itemCounter}`;
  item.textContent = nome;

  item.addEventListener('dragstart', () => item.classList.add('dragging'));
  item.addEventListener('dragend', () => item.classList.remove('dragging'));
  item.addEventListener('contextmenu', handleContextMenu); // Menu de contexto para o item

  grupo.appendChild(item);
}

// Evento de adicionar grupo
addGrupoButton.addEventListener('click', () => {
  const nomeGrupo = nomeNovoGrupoInput.value.trim();
  if (nomeGrupo) {
    createGrupo(nomeGrupo);
    nomeNovoGrupoInput.value = '';
    saveKanbanToCookie(); // Salva o estado após adicionar o grupo
  }
});

// Evento de adicionar item
addItemButton.addEventListener('click', () => {
  const nomeItem = nomeNovoItemInput.value.trim();
  const grupoInicial = document.getElementById('grupo-inicial');
  if (nomeItem && grupoInicial) {
    createItem(nomeItem, grupoInicial);
    nomeNovoItemInput.value = '';
    saveKanbanToCookie(); // Salva o estado após adicionar o item
  }
});

/**
 * Gerencia o menu de contexto para itens
 * @param {Event} event - O evento de clique com o botão direito
 * @function
 */
function handleContextMenu(event) {
  event.preventDefault();
  const { clientX, clientY } = event;
  currentItem = event.target; // Armazena o item atual
  contextMenu.style.left = `${clientX}px`;
  contextMenu.style.top = `${clientY}px`;
  contextMenu.style.display = 'block';
}

/**
 * Gerencia o menu de contexto para grupos
 * @param {Event} event - O evento de clique com o botão direito
 * @function
 */
function handleContextMenuGrupo(event) {
  event.preventDefault();
  const { clientX, clientY } = event;
  currentGrupo = event.target.closest('.titulo-grupo'); // Armazena o grupo atual
  contextMenuGrupo.style.left = `${clientX}px`;
  contextMenuGrupo.style.top = `${clientY}px`;
  contextMenuGrupo.style.display = 'block';
}

/**
 * Fechar os menus de contexto ao clicar fora deles
 * @param {Event} event - O evento de clique
 * @function
 */
document.addEventListener('click', (event) => {
  if (!contextMenu.contains(event.target) && !contextMenuGrupo.contains(event.target)) {
    contextMenu.style.display = 'none';
    contextMenuGrupo.style.display = 'none';
  }
});

/**
 * Função para gerenciar o drag-and-drop de itens entre grupos
 * @param {Event} event - O evento de arrastar
 * @function
 */
function handleDragOver(event) {
  event.preventDefault();
  const dragging = document.querySelector('.dragging');
  const target = event.target.closest('.grupo');
  if (target) {
    target.appendChild(dragging);
  }
}

/**
 * Funcionalidade de Editar Item
 * @function
 */
editarItemOption.addEventListener('click', () => {
  if (currentItem) {
    const novoTexto = prompt('Editar Item:', currentItem.textContent);
    if (novoTexto) {
      currentItem.textContent = novoTexto;
      saveKanbanToCookie(); // Salva o estado após editar o item
    }
    contextMenu.style.display = 'none';
  }
});

/**
 * Funcionalidade de Excluir Item
 * @function
 */
excluirItemOption.addEventListener('click', () => {
  if (currentItem) {
    currentItem.remove(); // Remove o item atual
    saveKanbanToCookie(); // Salva o estado após excluir o item
    contextMenu.style.display = 'none';
  }
});

/**
 * Funcionalidade de Editar Grupo
 * @function
 */
editarGrupoOption.addEventListener('click', () => {
  if (currentGrupo) {
    const tituloGrupo = currentGrupo.querySelector('h1');
    const novoNome = prompt('Editar nome do Grupo:', tituloGrupo.textContent);
    if (novoNome) {
      tituloGrupo.textContent = novoNome;
      saveKanbanToCookie(); // Salva o estado após editar o grupo
    }
    contextMenuGrupo.style.display = 'none';
  }
});

/**
 * Funcionalidade de Excluir Grupo
 * @function
 */
excluirGrupoOption.addEventListener('click', () => {
  if (currentGrupo) {
    currentGrupo.remove(); // Remove o grupo
    saveKanbanToCookie(); // Salva o estado após excluir o grupo
    contextMenuGrupo.style.display = 'none';
  }
});

/**
 * Carregar o Kanban quando a página for carregada
 * @function
 */
window.onload = () => {
  loadKanbanFromCookie(); // Carrega o Kanban do cookie
};

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

/**

* Obtém os elementos do DOM para manipulação posterior

* @type {HTMLElement}

const addGrupoButton = document.getElementById('add-grupo');

const addItemButton = document.getElementById('add-item');

const nomeNovoGrupoInput = document.getElementById('nome-novo-grupo');

const nomeNovoItemInput = document.getElementById('nome-novo-item');

const kanban = document.getElementById('kanban');

const contextMenu = document.getElementById('contextMenu');

const contextMenuGrupo = document.getElementById('contextMenuGrupo');

const editarItemOption = document.getElementById('editarItem');

const excluirItemOption = document.getElementById('excluirItem');

const editarGrupoOption = document.getElementById('editarGrupo');

const excluirGrupoOption = document.getElementById('excluirGrupo');

let itemCounter = 3; // Começa após o último item existente

let currentItem = null; // Referência ao item atual do menu de contexto

let currentGrupo = null; // Referência ao grupo atual do menu de contexto

/**

* Função para salvar o estado atual do Kanban no cookie

* @function

function saveKanbanToCookie() {

const grupos = [];

const grupoElements = document.querySelectorAll('.titulo-grupo');

grupoElements.forEach(grupoElement => {

const grupo = {

nome: grupoElement.querySelector('h1').textContent,

itens: []

};

const itemElements = grupoElement.querySelectorAll('.grupo .item');

itemElements.forEach(item => {

grupo.itens.push(item.textContent);

});

grupos.push(grupo);

});

// Converte os dados em JSON

const jsonData = JSON.stringify(grupos);

// Criptografa os dados

const encryptedData = CryptoJS.AES.encrypt(jsonData, 'secret-key').toString();

// Salva os dados criptografados no cookie

document.cookie = `kanbanData=${encryptedData}; path=/; max-age=${60 * 60 * 24 * 365}`;

}

/**

* Função para carregar o Kanban a partir do cookie

* @function

function loadKanbanFromCookie() {

const cookies = document.cookie.split('; ');

const kanbanCookie = cookies.find(cookie => cookie.startsWith('kanbanData='));

if (kanbanCookie) {

// Extrai e descriptografa os dados do cookie

const encryptedData = kanbanCookie.split('=')[1];

const bytes = CryptoJS.AES.decrypt(encryptedData, 'secret-key');

const jsonData = bytes.toString(CryptoJS.enc.Utf8);

// Converte de volta para um objeto

const kanbanData = JSON.parse(jsonData);

// Cria os grupos e itens a partir dos dados

kanbanData.forEach(grupo => {

createGrupo(grupo.nome); // Cria o grupo

const grupoElement = document.querySelector(`#kanban .titulo-grupo:last-child .grupo`);

grupo.itens.forEach(item => {

createItem(item, grupoElement); // Cria os itens dentro do grupo

});

}

/**

* Função para criar um novo grupo

* @param {string} nome - Nome do grupo a ser criado

* @function

function createGrupo(nome) {

const tituloGrupo = document.createElement('div');

tituloGrupo.className = 'titulo-grupo';

const grupo = document.createElement('div');

grupo.className = 'grupo';

grupo.addEventListener('dragover', handleDragOver);

const titulo = document.createElement('h1');

titulo.textContent = nome;

titulo.addEventListener('contextmenu', handleContextMenuGrupo); // Adicionando o menu de contexto para o título do grupo

tituloGrupo.appendChild(titulo);

tituloGrupo.appendChild(grupo);

kanban.appendChild(tituloGrupo);

}

/**

* Função para criar um novo item dentro de um grupo

* @param {string} nome - Nome do item a ser criado

* @param {HTMLElement} grupo - O grupo onde o item será adicionado

* @function

function createItem(nome, grupo) {

const item = document.createElement('div');

item.className = 'item';

item.draggable = true;

item.id = `item-${++itemCounter}`;

item.textContent = nome;

item.addEventListener('dragstart', () => item.classList.add('dragging'));

item.addEventListener('dragend', () => item.classList.remove('dragging'));

item.addEventListener('contextmenu', handleContextMenu); // Menu de contexto para o item

grupo.appendChild(item);

}

// Evento de adicionar grupo

addGrupoButton.addEventListener('click', () => {

const nomeGrupo = nomeNovoGrupoInput.value.trim();

if (nomeGrupo) {

createGrupo(nomeGrupo);

nomeNovoGrupoInput.value = '';

saveKanbanToCookie(); // Salva o estado após adicionar o grupo

}

});

// Evento de adicionar item

addItemButton.addEventListener('click', () => {

const nomeItem = nomeNovoItemInput.value.trim();

const grupoInicial = document.getElementById('grupo-inicial');

if (nomeItem && grupoInicial) {

createItem(nomeItem, grupoInicial);

nomeNovoItemInput.value = '';

saveKanbanToCookie(); // Salva o estado após adicionar o item

}

});

/**

* Gerencia o menu de contexto para itens

* @param {Event} event - O evento de clique com o botão direito

* @function

function handleContextMenu(event) {

event.preventDefault();

const { clientX, clientY } = event;

currentItem = event.target; // Armazena o item atual

contextMenu.style.left = `${clientX}px`;

contextMenu.style.top = `${clientY}px`;

contextMenu.style.display = 'block';

}

/**

* Gerencia o menu de contexto para grupos

* @param {Event} event - O evento de clique com o botão direito

* @function

function handleContextMenuGrupo(event) {

event.preventDefault();

const { clientX, clientY } = event;

currentGrupo = event.target.closest('.titulo-grupo'); // Armazena o grupo atual

contextMenuGrupo.style.left = `${clientX}px`;

contextMenuGrupo.style.top = `${clientY}px`;

contextMenuGrupo.style.display = 'block';

}

/**

* Fechar os menus de contexto ao clicar fora deles

* @param {Event} event - O evento de clique

* @function

document.addEventListener('click', (event) => {

if (!contextMenu.contains(event.target) && !contextMenuGrupo.contains(event.target)) {

contextMenu.style.display = 'none';

contextMenuGrupo.style.display = 'none';

}

});

/**

* Função para gerenciar o drag-and-drop de itens entre grupos

* @param {Event} event - O evento de arrastar

* @function

function handleDragOver(event) {

event.preventDefault();

const dragging = document.querySelector('.dragging');

const target = event.target.closest('.grupo');

if (target) {

target.appendChild(dragging);

}

/**

* Funcionalidade de Editar Item

* @function

editarItemOption.addEventListener('click', () => {

if (currentItem) {

const novoTexto = prompt('Editar Item:', currentItem.textContent);

if (novoTexto) {

currentItem.textContent = novoTexto;

saveKanbanToCookie(); // Salva o estado após editar o item

}

contextMenu.style.display = 'none';

}

});

/**

* Funcionalidade de Excluir Item

* @function

excluirItemOption.addEventListener('click', () => {

if (currentItem) {

currentItem.remove(); // Remove o item atual

saveKanbanToCookie(); // Salva o estado após excluir o item

contextMenu.style.display = 'none';

}

});

/**

* Funcionalidade de Editar Grupo

* @function

editarGrupoOption.addEventListener('click', () => {

if (currentGrupo) {

const tituloGrupo = currentGrupo.querySelector('h1');

const novoNome = prompt('Editar nome do Grupo:', tituloGrupo.textContent);

if (novoNome) {

tituloGrupo.textContent = novoNome;

saveKanbanToCookie(); // Salva o estado após editar o grupo

}

contextMenuGrupo.style.display = 'none';

}

});

/**

* Funcionalidade de Excluir Grupo

* @function

excluirGrupoOption.addEventListener('click', () => {

if (currentGrupo) {

currentGrupo.remove(); // Remove o grupo

saveKanbanToCookie(); // Salva o estado após excluir o grupo

contextMenuGrupo.style.display = 'none';

}

});

/**

* Carregar o Kanban quando a página for carregada

* @function

window.onload = () => {

loadKanbanFromCookie(); // Carrega o Kanban do cookie

};

CSS:

:root {
  --kanban-bg: #FFF4CF;
  --grupo-bg: #5FA06D;
  --item-bg: #ffffff;
  --context-menu-bg: #ffffff;
  --context-menu-border: #ccc;
}

* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
  font-family: 'Poppins', sans-serif;
}

body {
  font-size: 12px;
}

.kanban {
  display: flex;
  gap: 10px;
  padding: 10px;
  background: var(--kanban-bg);
  width: 100%;
  min-height: 400px;
}

.grupo {
  display: flex;
  flex-direction: column;
  gap: 10px;
  padding: 10px;
  background-color: var(--grupo-bg);
  border-radius: 5px;
  min-width: 200px;
  margin: 20px;
}

.item {
  background-color: var(--item-bg);
  padding: 10px;
  border-radius: 5px;
  cursor: grab;
}

.dragging {
  opacity: 0.5;
}

#formulario {
  display: flex;
  justify-content: space-around;
  padding: 10px;
  gap: 10px;
}

#formulario input,
#formulario button {
  padding: 5px;
  border-radius: 3px;
  border: 1px solid #ccc;
}

.context-menu {
  position: absolute;
  display: none;
  background: var(--context-menu-bg);
  border: 1px solid var(--context-menu-border);
  padding: 5px;
  border-radius: 3px;
}

.context-menu ul {
  list-style: none;
  padding: 0;
}

.context-menu li {
  padding: 5px;
  cursor: pointer;
}

.context-menu li:hover {
  background-color: #f0f0f0;
}

:root {

--kanban-bg: #FFF4CF;

--grupo-bg: #5FA06D;

--item-bg: #ffffff;

--context-menu-bg: #ffffff;

--context-menu-border: #ccc;

}

* {

margin: 0;

padding: 0;

box-sizing: border-box;

font-family: 'Poppins', sans-serif;

}

body {

font-size: 12px;

}

.kanban {

display: flex;

gap: 10px;

padding: 10px;

background: var(--kanban-bg);

width: 100%;

min-height: 400px;

}

.grupo {

display: flex;

flex-direction: column;

gap: 10px;

padding: 10px;

background-color: var(--grupo-bg);

border-radius: 5px;

min-width: 200px;

margin: 20px;

}

.item {

background-color: var(--item-bg);

padding: 10px;

border-radius: 5px;

cursor: grab;

}

.dragging {

opacity: 0.5;

}

#formulario {

display: flex;

justify-content: space-around;

padding: 10px;

gap: 10px;

}

#formulario input,

#formulario button {

padding: 5px;

border-radius: 3px;

border: 1px solid #ccc;

}

.context-menu {

position: absolute;

display: none;

background: var(--context-menu-bg);

border: 1px solid var(--context-menu-border);

padding: 5px;

border-radius: 3px;

}

.context-menu ul {

list-style: none;

padding: 0;

}

.context-menu li {

padding: 5px;

cursor: pointer;

}

.context-menu li:hover {

background-color: #f0f0f0;

}

HTML:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Kanban</title>
  <link rel="stylesheet" href="style.css" />
</head>
<body>
  <div id="contextMenu" class="context-menu">
    <ul>
      <li id="editarItem">Editar Item</li>
      <li id="excluirItem">Excluir Item</li>
    </ul>
  </div>

  <div id="contextMenuGrupo" class="context-menu">
    <ul>
      <li id="editarGrupo">Editar Grupo</li>
      <li id="excluirGrupo">Excluir Grupo</li>
    </ul>
  </div>

  <div id="formulario">
    <input id="nome-novo-grupo" type="text" placeholder="Nome do Grupo" />
    <button id="add-grupo">Adicionar Grupo</button>
    <input id="nome-novo-item" type="text" placeholder="Nome do Item" />
    <button id="add-item">Adicionar Item</button>
  </div>

  <div id="kanban" class="kanban">
    <div class="titulo-grupo">
      <h1>Start</h1>
      <div class="grupo" id="grupo-inicial"></div>
    </div>
  </div>

  <script src="script.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.9-1-crypto-js.min.js"></script
</body>
</html>

<!DOCTYPE html>

<head>

<title>Kanban</title>

</head>

<body>

<ul>

<li id="editarItem">Editar Item</li>

<li id="excluirItem">Excluir Item</li>

</ul>

</div>

<ul>

<li id="editarGrupo">Editar Grupo</li>

<li id="excluirGrupo">Excluir Grupo</li>

</ul>

</div>

<button id="add-grupo">Adicionar Grupo</button>

<button id="add-item">Adicionar Item</button>

</div>

<h1>Start</h1>

</div>

</body>

</html>

Referências:

Documentação JSDoc

livros sobre JavaScript

GitHub:

Projeto kanban_js

Interno:

Quem somos

Comentários, variáveis, documentação com JavaScript

18/01/202525/12/2024 Por antonino

Veremos neste post comentários, variáveis, documentação com JavaScript.

Comentários:

Os comentários desempenham um papel essencial ao melhorar a legibilidade do código, explicando partes relevantes e ajudando outros desenvolvedores a manterem o código, especialmente aqueles que não conhecem o projeto. Por isso, os desenvolvedores consideram os comentários indispensáveis.

Uma linha

// use comentários de uma linha // para anotações curtas e objetivas

1	// use comentários de uma linha // para anotações curtas e objetivas

Várias linhas

/* escreva comentários longos em múltiplas linhas. Isso funciona muito bem para explicações detalhadas. */

1	/* escreva comentários longos em múltiplas linhas. Isso funciona muito bem para explicações detalhadas. */

Eu recomendo que você insira comentários sempre que necessário, descrevendo o propósito de partes mais complexas do código e destacando observações importantes. Dessa forma, os leitores futuros entendem o projeto mais facilmente.

Declaração de variáveis:

Declarar variáveis de maneira adequada constitui uma prática essencial em JavaScript. Você pode fazer isso utilizando var, let e const. Cada uma dessas opções apresenta características específicas que influenciam diretamente o escopo e o comportamento das variáveis no código.

Var

Ao usar var, você define variáveis com escopo de função. Isso significa que elas permanecem acessíveis em qualquer parte da função onde foram declaradas, mesmo fora de blocos delimitados por chaves. No entanto, você deve ter cuidado com o hoisting, pois ele pode gerar comportamentos inesperados.

if (true) {
    var x = 10;
}
console.log(x); // 10

if (true) {

var x = 10;

}

console.log(x); // 10

Let

Quando utilizamos let, o escopo da variável se restringe ao bloco onde foi declarado. Esse comportamento contribui para evitar conflitos e diminui os erros causados por sobreposição de variáveis.

if (true) {
    let y = 20;
}
console.log(y); // ReferenceError: y is not defined

if (true) {

let y = 20;

}

console.log(y); // ReferenceError: y is not defined

Declaração de constantes:

Const

Constantes declaradas com const possuem escopo de bloco, da mesma forma que let. No entanto, ao contrário das variáveis, seu valor não pode ser alterado após a inicialização. Isso as torna particularmente úteis para armazenar valores fixos durante a execução do programa.

if (true) {
    const y = 20;
}
console.log(y); // ReferenceError: y is not defined

if (true) {

const y = 20;

}

console.log(y); // ReferenceError: y is not defined

Como saber o browser do usuário:

O navegador utilizado desempenha um papel importante na forma como o conteúdo é exibido. Por exemplo, o formato de imagem WebP é extremamente eficiente e promissor. Contudo, nem todos os navegadores oferecem suporte a ele. Assim, para proporcionar a melhor experiência ao usuário, identificar o navegador em uso e adaptar o conteúdo é uma estratégia útil.

/**
 * Identifica o navegador utilizado pelo cliente com base no user agent.
 * 
 * @returns {string} O nome do navegador identificado. Retornos possíveis:
 * - "Chrome": Caso o user agent indique o navegador Chrome.
 * - "Firefox": Caso o user agent indique o navegador Firefox.
 * - "Safari": Caso o user agent indique o navegador Safari.
 * - "Internet Explorer": Caso o user agent indique o navegador Internet Explorer.
 * - "Edge": Caso o user agent indique o navegador Edge.
 * - "Outro": Quando o navegador não for identificado pelos critérios acima.
 * 
 * @example
 * // Exemplo de uso:
 * const navegador = getBrowser();
 * console.log(navegador); // Pode retornar "Chrome", "Firefox", etc.
 */
function getBrowser() {
    const userAgent = navigator.userAgent;
    if (userAgent.indexOf("Chrome") > -1) {
        return "Chrome";
    } else if (userAgent.indexOf("Firefox") > -1) {
        return "Firefox";   
    } else if (userAgent.indexOf("Safari") > -1) {
        return "Safari";   
    } else if (userAgent.indexOf("MSIE") > -1 || userAgent.indexOf("Trident") > -1) {
        return "Internet Explorer";
    } else if (userAgent.indexOf("Edge") > -1) {
        return "Edge";
    } else {
        return "Outro";
    }
}

/**

* Identifica o navegador utilizado pelo cliente com base no user agent.

* @returns {string} O nome do navegador identificado. Retornos possíveis:

* - "Chrome": Caso o user agent indique o navegador Chrome.

* - "Firefox": Caso o user agent indique o navegador Firefox.

* - "Safari": Caso o user agent indique o navegador Safari.

* - "Internet Explorer": Caso o user agent indique o navegador Internet Explorer.

* - "Edge": Caso o user agent indique o navegador Edge.

* - "Outro": Quando o navegador não for identificado pelos critérios acima.

* @example

* // Exemplo de uso:

* const navegador = getBrowser();

* console.log(navegador); // Pode retornar "Chrome", "Firefox", etc.

function getBrowser() {

const userAgent = navigator.userAgent;

if (userAgent.indexOf("Chrome") > -1) {

return "Chrome";

} else if (userAgent.indexOf("Firefox") > -1) {

return "Firefox";

} else if (userAgent.indexOf("Safari") > -1) {

return "Safari";

} else if (userAgent.indexOf("MSIE") > -1 || userAgent.indexOf("Trident") > -1) {

return "Internet Explorer";

} else if (userAgent.indexOf("Edge") > -1) {

return "Edge";

} else {

return "Outro";

}

Identificar o navegador do usuário é um passo fundamental para adaptar o conteúdo de forma eficaz. Isso garante compatibilidade e oferece uma experiência aprimorada, independentemente do dispositivo ou navegador utilizado pelo cliente.

Criar a Documentação JavaScript

Para documentar seu código JavaScript de forma eficiente e padronizada, você pode recorrer à poderosa biblioteca JSDoc. Essa ferramenta facilita a criação de uma documentação clara e bem estruturada para o seu projeto.

Os comentários no exemplo acima servem como base para desenvolver uma documentação completa. Para que a documentação seja realmente útil, é essencial comentar todas as funções, classes, variáveis globais e constantes do código.

Ao comentar funções, não se esqueça de incluir informações como os parâmetros recebidos (@param), o tipo de retorno (@returns) e exemplos claros de uso (@example). Dessa forma, você esclarece o funcionamento do código de maneira detalhada e prática.

Instale o JSDoc com:

npm install jsdoc -g

1	npm install jsdoc -g

Esse comando instalará o JSDoc globalmente, permitindo que você o utilize em qualquer projeto JavaScript sempre que necessário.

Gere a documentação com:

npx jsdoc src -d docs

1	npx jsdoc src -d docs

Com este comando, você analisa o código no diretório src, processa os comentários JSDoc e gera uma documentação em HTML no diretório docs. Certifique-se de que os comentários no código estejam bem estruturados e informativos, já que eles são convertidos diretamente no conteúdo da documentação.

Seguindo essas etapas, você cria uma documentação profissional, que facilita a compreensão do código e apoia a manutenção por outros desenvolvedores no futuro.

Referências:

Documentação JSDoc

livros sobre JavaScript

Interno:

Área de Convivência