A importância de uma boa documentação

Artigo sobre a importância de se ter um software bem documentado.

por Bruno Henrique Zulzke

Quando comecei a desenvolver softwares não fazia idéia do que se tratava, porém ao longo dos anos foi se tornando cada vez mais comum ouvir a palavra Documentação, e com a vivência em projetos e estudos na faculdade, pude ter a visão exata de como é importante ter um software com uma boa documentação.

Na minha visão entendo como um software bem documentado quando o mesmo possui um código bem estruturado e comentado para futuros programadores que poderão entrar no meio do projeto, um documento com especificações e instruções tanto para o usuário final como para outros programadores e por fim seus testes devidamente executados com sucesso para garantir o funcionamento das funcionalidades que o software está proposto a executar.

Neste artigo abordaremos sobre a qualidade do código fonte.

O que é um código bem escrito?

Um bom programador deve ter em mente que não está escrevendo o código para si mesmo, e sim está escrevendo um código que deve ser entendível a qualquer outro programador que por um acaso precisará ter que mexer no sistema, e pra isso acontecer é muito importante seguir algumas boas práticas de desenvolvimento de software, com algumas que veremos abaixo:

Nomenclatura de métodos e variáveis

Tente sempre manter um padrão de nomes em seus métodos e variáveis e lembre-se sempre de colocar nomes que realmente condizem com o que a variável ou método faz.

Outra dica é sempre seguir os padrões que sua linguagem recomenda, como por exemplo, os nomes de métodos sempre começando com maiúscula:

Ex: public void MeuMetodo()...

Comentários

Lembre-se sempre de comentar seu código, pois provavelmente outro programador ou até mesmo você no futuro irá precisar fazer alguma manutenção em seu código, e comentários vão economizar um bom tempo do seu trabalho.

Escreva comentários coerentes e que possam ser úteis como, por exemplo, comentários que possam lhe ajudar a se lembrar de alguma regra de negócio que o trecho de código está executando.

Evite comentários do tipo “Insere dados na tabela usuários”. Isso não será útil, já que isso pode ser lido claramente no código e esse comentário só irá consumir linhas de seu projeto.

Identação

Um código bem identado facilita a leitura e já é meio caminho andado para o entendimento do código, por isso, dê bastante atenção a esse quesito.

Hoje em dia a maioria das IDEs fazem esse serviço automaticamente como o (Visual Studio, Netbeans, Eclipse...).

Acoplamento x Coesão

Um bom software deve ser bastante coeso e com baixo acoplamento, o que isso quer dizer?

Quer dizer que seu código deve ser separado por “módulos” onde quanto menos uma parte precisar da outra melhor (Acoplamento) e cada parte dessas executar exatamente o que se propôs a fazer (Coesão).

Por tanto na hora de escrever seu código, pense bem e separe as responsabilidades, se uma classe se chama “Usuarios”, coloque somente métodos referentes aos usuários, se um método se chama “Inserir Usuário”, garanta que ele faça somente a inclusão de um usuário.

Lembre-se: Um bom programador sempre é preguiçoso, por isso, sempre escreve códigos que podem ser reutilizáveis evitando o retrabalho.

Para concluir, antes de começar a escrever seu código leve esses tópicos em consideração, pois isso fundamental para definir se seu programa é ou não bem documentado e bem escrito.

Abraços.