Você está na página 1de 9

PADRES E DOCUMENTAO

Roberto Brasileiro
www.robertobrasileiro.com.br
Abril, 2009

Roberto Brasileiro
Padres e Documentao

FORMATAO DE ARQUIVOS PHP


IDENTAO
o

Tabulao em 4 espaos.

TAMANHO MXIMO DA LINHA


o

Tamanho mximo da linha deve ser de 120 caracteres.

TERMINO DA LINHA
o
o
o

Linhas devem terminar apenas com Linefeeds (LF) [\n]


No usar Carriage Return (CR) [\r], padro Macintosh
No usar a combinao (CR) (LF) [\r\n], padro Windows

Roberto Brasileiro
www.robertobrasileiro.com.br

Roberto Brasileiro
Padres e Documentao

PHPDOCUMENTOR (PHPDOC)
O phpDocumentor o mais utilizado para auto-documentao da linguagem PHP. Similar ao Javadoc, e
desenvolvido em PHP, pode ser usado da linha de comando ou atravs de uma interface web para criar
documentao profissional para cdigos-fonte PHP.

O QUE UTILIZAR?
o
o
o

Utilizar apenas tags necessrias ao nosso trabalho.


A ordem das Tags faz parte do padro de documentao.
Uma linha de documentao no deve passar de 80 caracteres.

TAGS
A utilizao das Tags do PHPDocumentor ir depender do que estaremos documentando. O contexto de
documentao pode variar de uma linha de cdigo a uma classe do sistema a ser desenvolvido.

ORDEM DAS TAGS


Para se ter uma melhor visibilidade e clareza na documentao, as tags utilizadas devem seguir a seguinte
estrutura. Para facilitar dividiremos o bloco de documentao em vrios blocos pequenos, separados
sempre por uma linha em branco.

NOME DO BLOCO

DESCRIO

DocBlock

Definio
Autores
Controle
File Source
Acesso
Varivel
Parmetros
Retorno
Utilizao
See

Deve ser destinada a explicao do cdigo a ser documentado.


Autor ou autores do cdigo.
Informaes de verso, pacote, sub-pacote e data de criao.
Dever conter a Tag para exibir o cdigo do arquivo.
Informaes nveis de acesso.
Tipo e descrio da varivel ou atributo.
Informaes sobre os parmetros.
Informaes sobre o retorno de um mtodo ou funo.
Informam quais classes aquele cdigo utiliza.
Utilizados para incluses e arquivos requeridos pela aplicao.

Roberto Brasileiro
www.robertobrasileiro.com.br

Roberto Brasileiro
Padres e Documentao

DOCUMENTAO DO CDIGO
CLASSES E ARQUIVOS
A estrutura para documentao de classes e arquivos a seguinte:
[Definio]
[Autores]
[Controle]
[Utilizao] Se precisar.
[File Source]

MTODOS E FUNES
A estrutura para documentao de mtodos e funes a seguinte:
[Definio]
[Autores]
[Acesso]
[Parmetros]
[Utilizao]
[Retorno]

VARIVEIS E ATRIBUTOS
A estrutura para documentao de variveis e funes a seguinte:
[Varivel]
[Acesso] Em caso de atributos

Roberto Brasileiro
www.robertobrasileiro.com.br

Roberto Brasileiro
Padres e Documentao

BLOCO DE CDIGO
Existem duas maneiras de documentar um bloco de cdigo, que ir depender da relevncia ou complexidade do
cdigo.

PHPDOCUMENTOR
Para que a documentao de um bloco de cdigo faa parte da documentao a ser gerada utilize as Tag
do PHPDocumentor /** Texto */

DOCUMENTAO EM CDIGO
Para documentar um trecho de cdigo que ser relevante apenas para alteraes ou servir como
lembretes para outros desenvolvedores, deve-se utilizar o padro do PHP para comentrios, // Texto.

INCLUDES E REQUIRES
Documentar arquivos que sero includos ou requeridos durante a execuo, deve-se utilizar o bloco See.
[See]

Roberto Brasileiro
www.robertobrasileiro.com.br

Roberto Brasileiro
Padres e Documentao

UTILIZAO DAS TAGS


A utilizao das Tags deve seguir o padro a seguir.

TAG

BLOCO

UTILIZAO

@author
@version
@access
@static
@param
@return
@uses
@see

Autores
Controle
Acesso
Acesso
Parmetro
Retorno
Utilizao
See

@author Nome Sobrenome


@version 1.0.0
@access public | private | protected
@static
@param Tipo $Var Descrio
@return Tipo | void
@uses Classe | Funo
@see Classe | Arquivo

OBSERVAES
A utilizao das tags depende exclusivamente do cdigo que est sendo documentado. Por exemplo, as tags:
@static, @uses e @param.

Roberto Brasileiro
www.robertobrasileiro.com.br

Roberto Brasileiro
Padres e Documentao

NOMENCLATURAS
PADRO CAMELCASE
o

um padro largamente utilizado em diversas linguagens de programao, como PHP, Java, Ruby e
Python, principalmente nas definies de Classes e Objetos.

UTILIZAO
UPPERCAMELCASE
o

Classes
 IndexController, ControlModule, Uploads

LOWER COMELCASE

o
o

Variveis
 $intCount, $strName, $tmpQuery
 Utilizar nas iniciais qual o tipo da varivel, para melhorar a visibilidade do cdigo e o
entendimento.
Atributos
 $this->id, self::tableName, parent::filedId
Mtodos e Funes
 $this->getName(), self::getId(), parent::multiQuery()
 Mtodos privados devem possuir _ antes do nome.
$this->_execute(), self::_log()

UPPERCASE E _
o

Constantes
 NOT_EXIST, FETCH_ARRAY, DB_NAME

Roberto Brasileiro
www.robertobrasileiro.com.br

Roberto Brasileiro
Padres e Documentao

ESTILO DE CDIGO (CODING STYLE)


DEMARCAO DO CDIGO PHP
o

Short Tags <? ou <?=


 Utilizao somente para templates , utilizando somente quando tiver apenas uma linha
de cdigo, evitar o uso em estruturas de controle como FOR, FOREACH, IF e WHILES.
<?= $this->sumAssociations; ?>
Tags completas <?php ou <?php echo
 Utilizar em todos os arquivos ou scripts que sejam totalmente codificados em PHP.
Classes e Arquivos.

ASPAS
Existem diferentes ocasies para a utilizao das Aspas, onde depende completamente do contexto, onde a string
est inserida.

STRINGS LITERAIS
Se a string no contiver variveis de substituio, devem-se utilizar aspas simples.
o

$tmpQuery = SELECT id FROM users WHERE name = Fulano;

No utilizar aspas duplas, para evitar a utilizao de slashes [\].

CONCATENAO DE STRINGS
No utilizar substituio de variveis, dentro de uma string. Sempre concatenar.
o

No utilizar

Utilizar

o
o

$tmpQuery = SELECT id FROM users WHERE name = $strName;


$tmpQuery = SELECT id FROM users WHERE name = . $strName . ;

Roberto Brasileiro
www.robertobrasileiro.com.br

Roberto Brasileiro
Padres e Documentao

ESTRUTURAS DE CONTROLE
IF/ ELSE / ELSE IF
o
o

Usar espao simples depois do "(" e antes do ")" da condiao no IF e no ELSEIF


A chave { vir na linha de baixo da condio.

SWITCH / WHILE / FOR / FOREACH


o
o

Usar espao simples depois do "(" e antes do ")".


No SWITCH, sempre identar o cdigo do CASE com uma tabulao (4 espaos).
Todo o cdigo deve ser identado.

Roberto Brasileiro
www.robertobrasileiro.com.br