Porque documentar corretamente sua aplicação?

Porque documentar corretamente sua aplicação?

26/09/2017 às 16:00WordPress

Muitas vezes programadores precisam atualizar seus códigos para trazer novas funções, corrigir algum problema que foi descoberto ou mesmo assumir a manutenção de uma aplicação desenvolvida por outra pessoa, tudo isso faz parte da rotina comum de qualquer desenvolvedor. Mas quem nunca acabou tendo que atualizar um código e ao abrir uma das páginas para localizar uma função percebeu que estaria completamente perdido porque não existia nenhuma explicação de como tudo aquilo funcionava?
É claro que tudo pode ser contornado, mas cada um programa de maneira diferentes, e ter instruções de como determinada tarefa foi planejada ajuda não só quem a descreveu, mas também quem vier a manusear esses arquivos futuramente. Uma aplicação não documentada pode parecer irrelevante para alguns, mas vamos listar alguns dos prejuízos causados por esse detalhe tão relevante para qualquer ambiente e linguagem. Preparamos também uma dica bônus que vai te ajudar a dar uma função extra para a sua Hospedagem de Site.

Quando a falta de documentação passa despercebida?

A falta desse recurso pode não ser um fator decisivo quando aplicada em projetos muito simples, que não requer muito código e nem mesmo chega a utilizar grandes funções para solucionar problemas. Em sites de poucas páginas e apenas um formulário de contato, a documentação realmente se torna algo irrelevante, digamos assim, pela falta de “espaço” onde ela se torne essencial, os desenvolvedores podem se dar ao luxo de abrir mão dessa tarefa e se dedicarem inteiramente a criação, testes e entrega do projeto.
Não é por esse detalhe que você não deve se preocupar com outras coisas, como já falamos em outro artigo sobre como proteger seus formulários contra SQL Injection e como trabalhar com validação de formulários, com esses dois textos você consegue de forma resumida entender a importância e como aplicar as medidas necessárias para se ver livre desses problemas até mesmo nos projetos mais simples.

A perda de produtividade em grandes projetos

Ainda que o trabalho em grandes projetos te dê mais tempo para trabalhar, tem prazos maiores, você certamente não tem um único projeto para administrar. Ainda que você tenha uma equipe, atender a demanda de dois ou três clientes dentro de um mesmo fluxo de trabalho pode ser um pouco complicado, se você não controlar corretamente as suas prioridades e a maneira como cada projeto irá se desenvolver, poderá ter problemas bem incômodos com o passar do tempo, seja pelo atraso na entrega, funções que ainda não estão funcionando corretamente, e quem sabe até confundir os projetos e implementar algo no lugar errado.
Quando falamos de trabalhos múltiplos, o ganho de produtividade se torna um luxo que você não pode de forma alguma abrir mão, poder ter uma folga para alguma emergência é fundamental para evitar problemas futuros que podem comprometer a visão do cliente com o seu trabalho, e é aí que entra a documentação adequada.

Quando você tem projetos maiores, com frameworks populares e diversos módulos para gerenciar, fica mais clara a necessidade de manter um rico detalhe do que está sendo criado. Imagine-se com três projetos em mãos, e ao se deparar com a necessidade de corrigir um problema informado pelo cliente, precisar de horas para lembrar onde aquela função é carregada, quais variáveis estão envolvidas no processo, se existe a chamada de outros arquivos, ou seja, um problema que poderia ter sido resolvido em alguns minutos se você tivesse todas essas informações, acaba se estendendo por horas a fio até que você consiga se encontrar novamente. Agora imagine se esse mesmo problema ocorre nos outros projetos? Quanto tempo você está perdendo por não saber o que o seu código está fazendo?

Em um sistema que já está em produção, os problemas com essa perda de produtividade e possibilidades maiores de erros por conta da falta de uma documentação é ainda mais grave, o que pode causar falhas em outras áreas do site, erros de processamento de dados ou mesmo deixar suas páginas offline em algum momento. E isso sem dúvidas pode resultar em perda de clientes, de dinheiro e posicionamento nas ferramentas de busca.

Você pode acessar algumas dicas de produtividade com editores de código, com isso você pode começar a criar sua rotinha que não deixará mais de lado a documentação, cria um bom hábito e passa a ter mais tempo para investir em outras coisas, que que passará menos tempo tentando descobrir como aquela função funcionava.

Dica bônus

Se você tem um espaço extra na sua hospedagem, porque não usar para servir como armazenamento das suas documentações? Aplicações como o Natural Docs podem te ajudar de forma prática e rápida a gerar suas páginas contendo as informações mais valiosas para a documentação da sua aplicação, tais como o uso, funções importantes, formas de implementação, entre outras. Tudo isso acessíveis de forma simples em páginas html e que vão carregar extremamente rápido para te ajudar sempre que necessário. Você pode inclusive começar hoje um teste grátis de 30 dias, ponha tudo em prática e surpreenda seus clientes.

Conclusão

Não é difícil começar a se aventurar nessa área da programação, documentação também faz parte de tudo isso e podemos até mesmo considerar uma tarefa de extrema importância, que envolve todos os passos da criação, manutenção e evolução do seu código. Existem muitas ferramentas que podem te auxiliar na geração de documentos complementares em html ou outros arquivos, e com nossa dica bônus você ainda tem a possibilidade de ter todas essas informações acessíveis online para qualquer um de seus clientes.

Gostou de nosso post? Compartilhe: