Olá Galera,

Faz um tempo que não escrevo em meu blog devido uma grande demanda de trabalhos neste mundo doido de Magento.

Por conta da falta de qualidade que tenho visto no mercado de software, não apenas brasileiro, mas em muitos outros países, tive a iniciativa de criar uma seção sobre boas práticas no desenvolvimento em Magento.

Na maioria do que tenho visto existe uma falha muito grande de conceitos e boas práticas no desenvolvimento. Acho interessante comentar um pouco aqui sobre o que tenho aprendido em todo este tempo com o qual trabalho com a plataforma.

Neste post eu vou falar um pouco sobre a documentação de código PHP no Magento e suas importâncias para a manutenção das personalizações feitas por empresas e profissionais liberais.

Documentação de Código

Este é um dos pontos que podem ajudar, e muito, a compreensão do código por qualquer desenvolvedor. É imprescindível que o código esteja bem documentado. Além de deixar seu código mais bonito e compreensível, a documentação do mesmo pode vir a tirar muitas dúvidas quando qualquer outro desenvolvedor, ou até o próprio criador do código, tiver que fazer algum tipo de alteração no mesmo.

Todos software, em sua entrega precisa(ria) de documentação do projeto, e é exatamente aqui aonde está o grande ganho de tempo. Você fazendo a documentação correta no seu código num padrão específico de alguma ferramenta de documentação, como o PHPDoc, no final do projeto, você poderia utilizar a ferramenta de documentação escolhida para gerar a documentação de toda a sua aplicação, ou seja, toda a documentação técnica já está pronta! Basta compartilhar com o cliente :).

Se você não é habituado com documentação de código ou não conhece o PHPDoc, aqui está uma grande oportunidade de ler um pouco mais sobre ele e passar a utilizar agora mesmo. Basta clicar neste link.

Documentação de Tipo de Entrada e Saída de Métodos

Para que um método fique mais claro e preciso é necessário que cada parâmetro esteja corretamente declarado e tipado no código. A saída do resultado também precisa ser devidamente tipada. Vejam abaixo um método de exemplo:

[php title=”Documentação de Tipo de Entrada e Saída de Métodos”]
/**
* Prefix the seller store id to product’s sku.
*
* @param Varien_Event_Observer $observer
*
* @return MarketPlace_Catalog_Model_Observer|void
*
* @author Tiago Sampaio <tiago @tiagosampaio.com>
*/
public function prependSellerStoreIdToSku(Varien_Event_Observer $observer)
{
/**
* If there is no seller_store_id or sky then do nothing.
*/
if (!$observer->getProduct()->getSellerStoreId() || !$observer->getProduct()->getSku()) {
return $this;
}

/** @var MarketPlace_Catalog_Helper_Data $helper */
$helper = Mage::helper(‘marketplace_catalog’);
if (!$helper->isProductSkuPrefixed($observer->getProduct())) {
$helper->prepareProductSku($observer->getProduct());
}
}
[/php]

Vejam que neste exemplo eu declaro o tipo de entrada para Varien_Event_Object tanto na documentação com a key @param quanto no próprio método para que ele aceite apenas objetos deste tipo e os possíveis tipos de saída que seriam um void, aonde não existirá retorno, ou o próprio objeto (MarketPlace_Catalog_Model_Observer) também declarados na documentação do método com a key @return. Fazendo este tipo de documentação fica muito mais fácil de se compreender o que deve ser passado para aquele método e saber o que ele retornará e preparar a sua aplicação para trabalhar com o mesmo. Além da fácil compreensão podemos assumir que o parâmetro passado terá sempre o mesmo tipo e ficarmos mais tranquilos ao se trabalhar com ele, por exemplo, o meu parâmetro será $observer e terá sempre o tipo Varie_Event_Observer, com isso em mente eu sei que vou sempre poder utilizar os métodos $observer->getData('key') ou $observer->getEvent().

Também temos uma outra grande vantagem que são os auto-completes. Para quem usa IDEs mais recentes com a possibilidade de integração com PHPDoc, por exemplo, como é o caso do PhpStorm, estará disponível os auto-completes de código no momento da escrita do código, o que facilita muito e poupa muito tempo da vida do desenvolvedor.

Documentação de Declaração de Tipo de Variável

Este tipo de documentação é muito importante também, pois ele declara os tipos de variáveis que temos em um determinado trecho de código. Veja o código a seguir:

[php title=”Documentação de Declaração de Tipo de Variável”]
public function prependSellerStoreIdToSku(Varien_Event_Observer $observer)
{
/** @var MarketPlace_Catalog_Helper_Data $helper */
$helper = Mage::helper(‘marketplace_catalog’);
if (!$helper->isProductSkuPrefixed($observer->getProduct())) {
$helper->prepareProductSku($observer->getProduct());
}
}
[/php]

Aqui neste código declaramos que a variável $helper é do tipo MarketPlace_Catalog_Helper_Data. Desta forma fica mais intuitivo sabermos o que o método Mage::helper('marketplace_catalog') retornará e que tipo de dados nossa variável terá.

Documentação de Descrição Sobre o Método

No exemplo anterior, reparem na primeira linha do comentário, é aonde eu declaro a finalidade daquele método. Por mais que esta prática seja menos utilizada, talvez por preguiça ou pela própria carreira do dia-a-dia, ela se faz necessária para que você compreenda o motivo daquele método existir. É importante que você saiba exatamente a finalidade do método e como ele pode te ajudar.

Documentação de Autoria do Código

Esta documentação é mais informativa e não obrigatória, normalmente serve como dedo-duro se o teu código der algum problema, porém se tudo ocorrer certo serve como impulsionador do teu nome. A key para se utilizar esta informação na documentação do PHPDoc é @author Pode ser utilizado tanto em métodos quanto em classes.

Documentação de Métodos Mágicos

Este tipo de documentação é menos usual, porém se faz bastante necessário também. Veja um exemplo abaixo:

[php autolinks=”true” gutter=”true” title=”Documentação de Métodos Mágicos”]
/**
* Catalog Product Model
*
* @method Mage_Catalog_Model_Resource_Product getResource()
* @method Mage_Catalog_Model_Product setHasError(bool $value)
* @method null|bool getHasError()
*
* @category Mage
* @package Mage_Catalog
* @author Magento Core Team <core @magentocommerce.com>
*/
class Mage_Catalog_Model_Product extends Mage_Catalog_Model_Abstract
{
…
}
[/php]

Temos mais uma nova key chamada @method que declara um método, ou métodos, mágicos de uma classe, neste caso a classe Mage_Catalog_Model_Product.

Documentação de Complexidade de Método

Veja o exemplo abaixo:

[php title=”Documentação de Complexidade de Método”]
public function prependSellerStoreIdToSku(Varien_Event_Observer $observer)
{
/**
* If there is no seller_store_id or sky then do nothing.
*/
if (!$observer->getProduct()->getSellerStoreId() || !$observer->getProduct()->getSku()) {
return $this;
}

$helper = Mage::helper(‘marketplace_catalog’);
if (!$helper->isProductSkuPrefixed($observer->getProduct())) {
$helper->prepareProductSku($observer->getProduct());
}
}
[/php]

Nele colocamos uma documentação cuja função é simplesmente explicar o porquê das coisas. Este tipo de documentação também não é obrigatória, porém ajuda muito na hora de você tentar compreender um trecho do código.

IDEs Integradas com o PHPDoc

Atualmente a maioria das IDEs já estão nativamente integradas com o PHPDoc, o que é uma mão na roda, pois já existem alto-completes para criar os tipos de documentação que citei acima. Por exemplo, no PhpStorm basta digitar /** e dar enter em cima de um método já criado que ele já completa o bloco de documentação com a tipagem de todos os parâmetros daquele método e sua respectiva saída ou dando espaço em cima de uma variável ele cria um bloco de declaração de tipo de variável /** @var My_Class $variable */. Com isso em mãos o desenvolvedor tem que ser muito preguiçoso pra não documentar o seu código, não acha? 🙂

Conclusão

Bom galera, acho que consegui passar rapidamente sobre a necessidade de uma boa documentação de código. Lembrando que existem muitas outras possibilidades e vantagens de se utilizar de uma boa documentação de código que eu não citei aqui neste post. Aconselho vocês a lerem um pouco mais sobre isso e a praticarem no seu dia-a-dia a documentação de todos os teus códigos. Configure hoje mesmo sua IDE para se integrar automaticamente com o PHPDocs e você não perderá quase nada de tempo documentando seu código.

Vou ficando por aqui. Um grande abraço.

Tiago Sampaio