Roberto Brasileiro

Bom pessoal, vamos lá!

Qual a pior coisa que acontece quando temos que pegar um código para dar manutenção ou melhoria? Entender o que se passou na cabeça de quem desenvolveu. Claro que existem várias exceções a essa regra, porém o que a experiência me mostrou e temos várias pessoas e equipes que utilizam sim documentações, mas se esquece de um fato primordial, padrão!

Imagine a seguinte situação… só você desenvolve um sistema e só você documenta e cria seus padrões… bom até ai não tem problema, afinal de contas estamos tratando com um desenvolvedor apenas, mas experimente adicionar mais quatro, cinco…dez desenvolvedores de diferentes níveis… o que teremos?

Bom, provavelmente teremos um código documentado, mas sem padrão algum! O grande problema dos desenvolvedores de hoje é que a maioria não sabe como e nem quando utilizar a maldita documentação.  Basta pensar, a documentação de código é um artefato pra quem? E quando utilizar?

Acredito que todos saibam que o PHPDoc é uma documentação a gerada para o próprio desenvolvedor, com ele podemos ter uma pequena noção do que se tem dentro de todo o sistema que está sendo construído ou que já está pronto.

Por já ter passado por alguns problemas, por falta de documentações e de padrão de código, hoje utilizo um “guia” que determina algumas regras na hora que vou desenvolver alguma aplicação. Esse guia minimizou diversos problemas no meu trabalho com outras pessoas.

Hoje, pelo formato do nome do arquivo sei do que se trata, se é classe ou script normal de php, por nomes de variáveis sei o tipo que está tratando… Porém o mais importante de uma documentação é ser condizente com o a realidade do seu código, de nada vai adiantar exagerar em utilizar tags e padrões que às vezes geram uma complexidade maior do que desenvolver a própria aplicação.

Documentação é código e por isso ela também deve ser funcional e limpa.

A documentação faz parte do código.

Estarei disponibilizando esse documento para download aqui.

Estou totalmente aberto a sugestões e criticas, espero ter ajudado….

Crédito à Walker Alencar, no qual assisti a palestra sobre Coding Standarts e me basiei, para fazer a minha versão.