Um código limpo e organizado permite uma relativa legibilidade do mesmo facilitando a sua compreensão e, por conseguinte, facilitando na manutenção e correção quando necessário.

Além das padronizações universais, adotadas por todos os profissionais do ramos, a convenção interna em alguns pontos específicos do trabalho realizado também é necessária para que toda a equipe possa estar coerente.

Este manual reuni as boas práticas, tanto as definidas pela comunidade em geral, quanto aquelas definidas pelo próprio grupo.

A adoção dessas práticas não é opcional, mas é importante que não se encarre tais regras como uma imposição, mas sim com a compreensão de que a coesão do time aumenta a eficiência e a eficácia do mesmo.

Comentários de Documentação

Comentários de documentação têm por objetivo, orientar aqueles que consomem o seu código, mas sem a necessidade de lerem o mesmo propriamente. Enriquecidas com um conjunto de parâmetros próprios, as diversas linguagens de programação oferecem ferramentas para tornar essa documentação, um processo rápido e fácil.

Este tipo de comentário pode preceder tanto os atributos quanto os métodos de uma classe, por exemplo.

Uma vez possuidores desses comentários, as ferramentas de desenvolvimento podem, a partir deles, gerar uma documentação considerando esses parâmetros.

Um exemplo desse tipo de comentário pode ser visto nos trechos provenientes da codificação padrão do Laravel, nos Controllers criados pela ferramenta Artsan, apresentado na figura seguinte:

O trecho de comentário apresentado na figura ilustra um Comentário de Documentação:

• Show the[…]: a primeira frase é uma descrição breve da função do método “show”;
• @param: a diretiva informa um parâmetro de entrada e o seu tipo;
• @return: já essa diretiva indica o retorno da função.

Sugestão de plugin para a ferramenta Atom: https://atom.io/packages/docblockr

Algumas linguagens de programação utilizam a endentação para delimitar os blocos de código. A endentação também é uma pratica muito importante para as linguagem que não a utiliza para delimitar blocos, pois permite aos programadores, identificar visualmente o início e o fim de um bloco de códigos.

É possível dizer que a base de dados de um sistema diz muito sobre o …

É fato que têm coisas auto-explicativas, dificilmente, em uma entidade Usuário, alguém não saberia a utilidade do atributo CPF.

Porém, é comum ocorrerem situações em que os valores dos atributos de uma entidade não sejam tão claros, por exemplo, em uma base, o atributo Situação da entidade Matrícula possui como ocorrências os valores 0, 1, 2 e 3. O que significa cada um desses valores para o atributo citado? Esse é um anti-padrão conhecido como “Números Mágicos”. Substituir esses números mágicos com contantes enumeradas, que possuem nome, quando possível, facilita a leitura, a compreensão e a manutenção.

Até mesmo para quem implementou esta entidade, pode ocorrer de, em uma manutenção posterior, não se lembrar mais o significado de cada valor que pode ocorrer.

Por isso, é extremamente importante comentar os atributos das entidades em uma base de dados. Lógico que o primeiro exemplo apresentado, do atributo CPF, não tem a necessidade de comentários, mas na dúvida, comente o atributo.

Lógico, o comentário tem que ser claro, objetivo e explicativo. No segundo exemplo apresentado, é possível indicar no comentário do atributo Situação, o que significa a ocorrência do valor 0, do 1 e assim por diante.

1. https://medium.freecodecamp.org/code-comments-the-good-the-bad-and-the-ugly-be9cc65fbf83
2. https://code.tutsplus.com/tutorials/top-15-best-practices-for-writing-super-readable-code--net-8118
3. https://improvingsoftware.com/2011/06/27/5-best-practices-for-commenting-your-code/
4. https://softwarepublico.gov.br/social/sei/manuais/padrao-de-codificacao-php/2-estruturacao-do-codigo
5. https://softwarepublico.gov.br/social/sei/manuais/padrao-de-codificacao-php/3-formatacao-do-codigo