Comentando seus códigos – seja amigo da sua memória

icon1 Postado por hlegius em PHP, Séries 04/09/2008 | 1 comentário

Esse post aqui é bem direto: padronização dos comentários dentro dos códigos da aplicação. Você usa ? Aliás, você sabe que existe isto ?

Aposto que sabe e espero que trabalhe de forma "documentada". Já cansei de mexer em scripts alheios para "dar manutenção" e encontrar métodos e mais métodos com nomes do cachorro, do computador ou da namorada para executar um simples upload, por exemplo. Isso é outro problema que depois a gente comenta. O foco é o que vem acima do:

PLAIN TEXT
PHP:
  1. public function foobar() { ... }

Pior que pegar uma função/método com o nome de foobar é pegar ela sem documentação alguma do que faz, o que retorna, o que lança em caso de falhas, de onde vem e pra onde vai.
Alguns ainda colocam um comentário lá nas coxas só pra não dizer que não falou de comentários do código, mas, acho que são poucos* ainda os que documentam melhor seus códigos.

Pra fechar o post sem muito lero-lero, vamos a um exemplo simples:

PLAIN TEXT
PHP:
  1. <?php
  2.  
  3. class ClientesController  {
  4.  
  5.     public function adiciona($arrCliente) { ... }
  6.  
  7. }

Obviamente ele "adicionará" um "Cliente". Mas, quais "inputs" ele espera receber, quais outputs eu devo preparar-me para receber e o que ele poderá lançar em caso de falhas ? Tudo é uma incógnita. Sim, sim ! Basta ler o código, mas e se eu resolver gerar a documentação do código como é que fica ?

Mas okay ! Vamos ver o mesmo código comentado!

PLAIN TEXT
PHP:
  1. <?php
  2. /**
  3. * objeto controlador do cliente dentro da aplicação. Ponte entre Model e View
  4. *
  5. * @author Foolano <foolano@servidor.com.br>
  6. *
  7. * @package Foo_root
  8. *
  9. * @created Mes, dd de YYYY
  10. * @revised ano-mes-dia hh:mm foolano
  11. */
  12. class ClientesController  {
  13.  
  14.     /**
  15.      * Adiciona um cliente novo no sistema xpto
  16.      *
  17.      * @param array $arrCliente (nome, idade, cep e e-mail)
  18.      *
  19.      * @return integer (contendo o id do novo cliente)
  20.      * @throws Exception (em caso de falhas na DAO ou na Model)
  21.      */
  22.     public function adiciona($arrCliente) { ... }
  23.  
  24. }

Melhorou um pouco, não ? Agora é contigo ! Isso ajuda futuros programadores que venham a mexer em seu sistema e, a si mesmo a menos que tenha uma memória de elefante.

Já vi também utilizarem uma barra invertida (\) no lugar dos arrobas (@), mas foi uma vez só e tem um tempinho já. O arroba é mais utilizado mesmo.



1 comentário para “Comentando seus códigos – seja amigo da sua memória”

  1. Diogo Silva says:
    04/09/2008 at 23:02

    Fato, documentar os códigos é algo muito importante. Usar o @ acho que é padrão, por funcionar com sistemas de documentação(como o PHPDOC).

    Lembro uma vez que um cliente pediu manutenção em um sistema, e dizia que eu tinha feito o sistema, mas eu não tinha a menor lembrança do sistema, era como se outra pessoa tivesso feito, pois estava muito diferente como construo atualmente.

    Por sorte o código estava razoavelmente comentado, principalmente na parte “critica” da aplicação, ao ler os comentários explicando o fluxo que caiu a ficha.Tinha até meu email lá rsrsrs

    Novamente, sequer lembro que sistema foi esse huahauhau.

    Abraços

    Reply

Comente !