|
|
@@ -0,0 +1,1204 @@
|
|
|
+<?xml version="1.0" encoding="UTF-8"?>
|
|
|
+<!-- EN-Revision: 24249 -->
|
|
|
+<!-- Reviewed: no -->
|
|
|
+<appendix id="coding-standard">
|
|
|
+ <title>Padrão de Codificação do Zend Framework para PHP</title>
|
|
|
+
|
|
|
+ <sect1 id="coding-standard.overview">
|
|
|
+ <title>Visão geral</title>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.overview.scope">
|
|
|
+ <title>Escopo</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Este documento fornece instruções para formatação e documentação de código a
|
|
|
+ indivíduos e times que contribuem com o Zend Framework. Muitos desenvolvedores que
|
|
|
+ utilizam o Zend Framework acham que estes padrões são igualmente importantes para
|
|
|
+ que seu estilo de codificação permaneça consistente com todo o código do Framework.
|
|
|
+ Vale também notar que é necessário esforço significativo para especificar padrões de
|
|
|
+ codificação por completo.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <note>
|
|
|
+ <para>
|
|
|
+ Por vezes, desenvolvedores consideram o estabelecimento de um padrão mais
|
|
|
+ importante do que o padrão sugere de verdade ao nível mais detalhado de design.
|
|
|
+ As instruções nos padrões de codificação do Zend Framework absorvem práticas que
|
|
|
+ funcionaram bem no projeto do Framework. Você pode alterar tais padrões ou
|
|
|
+ usá-los "as is" de acordo com os termos de nossa <ulink
|
|
|
+ url="http://framework.zend.com/license">licença</ulink>.
|
|
|
+ </para>
|
|
|
+ </note>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Os tópicos abordados nos padrões de codificação do Zend Framework incluem:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <itemizedlist>
|
|
|
+ <listitem>
|
|
|
+ <para>Formatação de arquivos <acronym>PHP</acronym></para>
|
|
|
+ </listitem>
|
|
|
+
|
|
|
+ <listitem>
|
|
|
+ <para>Convenções de nomenclatura</para>
|
|
|
+ </listitem>
|
|
|
+
|
|
|
+ <listitem>
|
|
|
+ <para>Estilo de codificação</para>
|
|
|
+ </listitem>
|
|
|
+
|
|
|
+ <listitem>
|
|
|
+ <para>Documentação em linha de código</para>
|
|
|
+ </listitem>
|
|
|
+ </itemizedlist>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.overview.goals">
|
|
|
+ <title>Objetivos</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Padrões de codificação são importantes em qualquer projeto de desenvolvimento, mas
|
|
|
+ são particularmente importantes quando muitos desenvolvedores estão trabalhando no
|
|
|
+ mesmo projeto. Eles ajudam a garantir que o código possua alta qualidade, poucos
|
|
|
+ bugs e possam ser facilmente mantidos.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+ </sect1>
|
|
|
+
|
|
|
+ <sect1 id="coding-standard.php-file-formatting">
|
|
|
+ <title>Formatação de Arquivos PHP</title>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.php-file-formatting.general">
|
|
|
+ <title>Geral</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Para arquivos que contenham somente código <acronym>PHP</acronym>, a tag de
|
|
|
+ fechamento ("?>") nunca é permitida. Ela não é exigida pelo <acronym>PHP</acronym> e
|
|
|
+ omiti-la previne a injeção acidental de espaços em branco desnecessários na
|
|
|
+ resposta.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <note>
|
|
|
+ <para>
|
|
|
+ <emphasis>Importante</emphasis>: A inclusão de dados binários arbitrários, como
|
|
|
+ permitido pela função <methodname>__HALT_COMPILER()</methodname>, é proibida a
|
|
|
+ partir de arquivos <acronym>PHP</acronym> no projeto Zend Framework ou de
|
|
|
+ arquivos derivados deles. O uso deste recurso é permitido somente para alguns
|
|
|
+ scripts de instalação.
|
|
|
+ </para>
|
|
|
+ </note>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.php-file-formatting.indentation">
|
|
|
+ <title>Indentação</title>
|
|
|
+
|
|
|
+ <para>A indentação deve consistir de 4 espaços. Tabulações não são permitidas.</para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.php-file-formatting.max-line-length">
|
|
|
+ <title>Comprimento máximo de linha</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ O comprimento desejável das linhas é 80 caracteres. Isto significa que
|
|
|
+ desenvolvedores do Zend Framework devem se esforçar para manter cada linha de seus
|
|
|
+ códigos com menos que 80 caracteres onde possível e prático. Entretanto, linhas
|
|
|
+ maiores são aceitáveis em algumas circunstâncias. O comprimento máximo de qualquer
|
|
|
+ linha de código <acronym>PHP</acronym> é 120 caracteres.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.php-file-formatting.line-termination">
|
|
|
+ <title>Quebra de linha</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Quebras de linha seguem a convenção de arquivos de texto Unix. As linhas devem
|
|
|
+ terminar com um único caractere de quebra -- linefeed (LF). Caracteres de quebra são
|
|
|
+ representados como ordinal 10 ou hexadecimal 0x0A.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Nota: Não use retornos -- carriage returns (CR) -- como é a convenção em arquivos
|
|
|
+ dos sistemas Apple (0x0D) ou a combinação de retorno e quebra
|
|
|
+ (<acronym>CRLF</acronym>), como é o padrão dos sistemas Windows (0x0D, 0x0A).
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+ </sect1>
|
|
|
+
|
|
|
+ <sect1 id="coding-standard.naming-conventions">
|
|
|
+ <title>Convenções de Nomenclatura</title>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.naming-conventions.classes">
|
|
|
+ <title>Classes</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ O Zend Framework utiliza um padrão de nomes de classes de forma que os nomes das
|
|
|
+ classes mapeiam diretamente os diretórios onde estão armazenadas. O diretório raiz
|
|
|
+ da biblioteca padrão do Zend Framework é o diretório "Zend/" e o diretório raiz da
|
|
|
+ biblioteca de extras é "ZendX/". Todas as classes do Zend Framework são armazenadas
|
|
|
+ hierarquicamente sob tais diretórios.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Nomes de classes devem conter somente caracteres alfanuméricos. Números são
|
|
|
+ permitidos em nomes de classes mas são desencorajados na maioria dos casos.
|
|
|
+ Underscores são permitidos somente no lugar de separador de diretórios. O arquivo
|
|
|
+ "<filename>Zend/Db/Table.php</filename>", por exemplo, deve mapear a classe de nome
|
|
|
+ "<classname>Zend_Db_Table</classname>".
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Se um nome de classe é composto de mais de uma palavra, a primeira letra de cada
|
|
|
+ nova palavra deve ser maiúscula. Letras maiúsculas em sequência não são permitidas.
|
|
|
+ A classe "Zend_PDF", por exemplo, não é permitida, enquanto
|
|
|
+ "<classname>Zend_Pdf</classname>" é.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Estas convenções definem um mecanismo de pseudonamespace para o Framework. O Zend
|
|
|
+ Framework irá adotar o recurso de namespace do <acronym>PHP</acronym> assim que ele
|
|
|
+ se tornar disponível e prático para nossos desenvolvedores os utilizarem em suas
|
|
|
+ aplicações.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Exemplos desta convenção de nomenclatura podem ser vistos em nomes de classes nas
|
|
|
+ bibliotecas padrão e de extras.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <note>
|
|
|
+ <para>
|
|
|
+ <emphasis>Importante</emphasis>: Códigos que devem ser disponibilizados junto às
|
|
|
+ bibliotecas do Zend Framework mas não são parte das bibliotecas padrão ou de
|
|
|
+ extras (por exemplo, código de aplicação ou bibliotecas que não são distribuídas
|
|
|
+ pela Zend) nunca devem iniciar com "Zend_" ou "ZendX_".
|
|
|
+ </para>
|
|
|
+ </note>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.naming-conventions.abstracts">
|
|
|
+ <title>Classes abstratas</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Em geral, classes abstratas seguem as mesmas convenções de <link
|
|
|
+ linkend="coding-standard.naming-conventions.classes">classes</link>, com uma
|
|
|
+ regra adicional: nomes de classes abstratas devem terminar com o termo "Abstract",
|
|
|
+ que não pode ser precedido por um underscore. Por exemplo,
|
|
|
+ <classname>Zend_Controller_Plugin_Abstract</classname> é considerado um nome
|
|
|
+ inválido, mas <classname>Zend_Controller_PluginAbstract</classname> ou
|
|
|
+ <classname>Zend_Controller_Plugin_PluginAbstract</classname> seriam nomes válidos.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <note>
|
|
|
+ <para>
|
|
|
+ Esta convenção de codificação é nova na versão 1.9.0 do Zend Framework. Classes
|
|
|
+ de datas anteriores a esta versão podem não seguir esta regra mas serão
|
|
|
+ renomeadas no futuro a fim de obedecê-la.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A razão de tal mudança é o uso de namespace. Como pretendemos que o Zend
|
|
|
+ Framework 2.0 utilize <acronym>PHP</acronym> 5.3, utilizaremos namespaces. A
|
|
|
+ maneira mais fácil de automatizar a conversão para namespaces é simplemente
|
|
|
+ converter underscores para o separador de namespace -- mas sob as antigas
|
|
|
+ convenções de nomenclatura isto deixa o nome da classe como somente "Abstract"
|
|
|
+ ou "Interface" -- as quais são palavras-chave reservadas em
|
|
|
+ <acronym>PHP</acronym>. Se prefixarmos o nome do (sub)componente ao nome da
|
|
|
+ classe, podemos evitar tais problemas.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Para ilustrar a situação, considere converter a classe
|
|
|
+ <classname>Zend_Controller_Request_Abstract</classname> para utilizar
|
|
|
+ namespaces:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+namespace Zend\Controller\Request;
|
|
|
+
|
|
|
+abstract class Abstract
|
|
|
+{
|
|
|
+ // ...
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Claramente isto não irá funcionar. Sob as novas convenções de nomenclatura,
|
|
|
+ entretanto, isso se tornaria:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+namespace Zend\Controller\Request;
|
|
|
+
|
|
|
+abstract class RequestAbstract
|
|
|
+{
|
|
|
+ // ...
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Ainda retemos a semântica e a separação de namespace enquanto omitimos os
|
|
|
+ problemas com palavras-chave; ao mesmo tempo, a classe abstrata é melhor
|
|
|
+ descrita.
|
|
|
+ </para>
|
|
|
+ </note>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.naming-conventions.interfaces">
|
|
|
+ <title>Interfaces</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Em geral, interfaces seguem as mesmas convenções de <link
|
|
|
+ linkend="coding-standard.naming-conventions.classes">classes</link>, com uma
|
|
|
+ regra adicional: nomes de interface podem opcionalmente terminar com o termo
|
|
|
+ "Interface", que não pode ser precedido por um underscore. Por exemplo,
|
|
|
+ <classname>Zend_Controller_Plugin_Interface</classname> é considerado um nome
|
|
|
+ inválido, mas <classname>Zend_Controller_PluginInterface</classname> ou
|
|
|
+ <classname>Zend_Controller_Plugin_PluginInterface</classname> seriam nomes válidos.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Embora esta regra não seja obrigatória, ela é fortemente recomendada, já que provê
|
|
|
+ uma boa pista visual aos desenvolvedores sobre quais arquivos contém interfaces em
|
|
|
+ vez de classes.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <note>
|
|
|
+ <para>
|
|
|
+ Esta convenção de nomenclatura é nova na versão 1.9.0 do Zend Framework. Classes
|
|
|
+ de datas anteriores a esta versão podem não seguir esta regra, mas serão
|
|
|
+ renomeadas no futuro a fim de obedecê-la. Veja <link
|
|
|
+ linkend="coding-standard.naming-conventions.abstracts">a seção
|
|
|
+ anterior</link> para informações sobre a razão da mudança.
|
|
|
+ </para>
|
|
|
+ </note>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.naming-conventions.filenames">
|
|
|
+ <title>Nomes de arquivos</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Para todos os outros arquivos, somente caracteres alfanuméricos, underscores e
|
|
|
+ hifens são permitidos. Espaços são estritamente proibidos.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Qualquer arquivo que contenha código <acronym>PHP</acronym> deve terminar com a
|
|
|
+ extensão "<filename>.php</filename>", com a notável exceção de scripts de view. Os
|
|
|
+ exemplos a seguir mostram nomes de arquivo aceitáveis para classes do Zend
|
|
|
+ Framework:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+Zend/Db.php
|
|
|
+
|
|
|
+Zend/Controller/Front.php
|
|
|
+
|
|
|
+Zend/View/Helper/FormRadio.php
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Nomes de arquivos devem mapear nomes de classes, como descrito acima.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.naming-conventions.functions-and-methods">
|
|
|
+ <title>Funções e métodos</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Nomes de funções devem conter somente caracteres alfanuméricos, não sendo
|
|
|
+ underscores permitidos. Números são permitidos mas desencorajados na maioria dos
|
|
|
+ casos.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Nomes de funções devem sempre começar com letra minúscula e, quando consistir de
|
|
|
+ mais de uma palavra, a primeira letra de cada palavra deve ser maiúscula. Esta
|
|
|
+ formatação é comumente chamada de "camelCase".
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A utilização de verbos é geralmente encorajada, devendo os nomes de funções ser tão
|
|
|
+ verbais quanto prático a fim de descrever de forma clara seu propósito e
|
|
|
+ comportamento.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Estes são exemplos de nomes aceitáveis de funções:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+filterInput()
|
|
|
+
|
|
|
+getElementById()
|
|
|
+
|
|
|
+widgetFactory()
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Para programação orientada a objetos, acessores de variáveis estáticas ou de
|
|
|
+ instância devem sempre ser prefixados com "get" ou "set". Ao implementar padrões de
|
|
|
+ design (“design patterns”), como o singleton ou o factory, o nome do método deve
|
|
|
+ conter o nome do padrão onde prático a fim de descrever claramente seu
|
|
|
+ comportamento.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Para métodos de objetos que são declarados com o modificador "private" ou
|
|
|
+ "protected", o primeiro caractere do nome do método deve ser um underscore. Esta é a
|
|
|
+ única aplicação aceitável de um underscore em um nome de método. Métodos declarados
|
|
|
+ como "public" nunca devem conter um underscore.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Funções em escopo global (também chamadas de "funções flutuantes") são permitidas
|
|
|
+ mas desencorajadas na maioria dos casos. Considere encapsular estas funções em uma
|
|
|
+ classe estática.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.naming-conventions.variables">
|
|
|
+ <title>Variáveis</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Nomes de variáveis devem conter somente caracteres alfanuméricos, não sendo
|
|
|
+ underscores permitidos. Números são permitidos mas são desencorajados na maioria dos
|
|
|
+ casos.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Para variáveis de instância declaradas com o modificador "private" ou "protected", o
|
|
|
+ primeiro caractere do nome da variável deve ser um underscore. Esta é a única
|
|
|
+ aplicação aceitável de um underscore em nome de variável. Variáveis-membras
|
|
|
+ declaradas com "public" nunca devem começar com um underscore.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Assim como nomes de funções (veja seção 3.3), nomes de variáveis devem sempre
|
|
|
+ começar com uma letra minúscula e seguir a convenção "camelCase".
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A utilização de verbos é encorajada, ou seja, variáveis devem sempre ser tão verbais
|
|
|
+ quanto prático para descrever os dados que o desenvolvedor pretende armazenar nelas.
|
|
|
+ Nomes concisos de variáveis como "<varname>$i</varname>" e "<varname>$n</varname>"
|
|
|
+ são desencorajados para todos os contextos de laço, exceto os menores. Se um loop
|
|
|
+ contém mais de 20 linhas de código então as variáveis de índice devem ter nomes mais
|
|
|
+ descritivos.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.naming-conventions.constants">
|
|
|
+ <title>Constantes</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Constantes devem conter tanto caracteres alfanuméricos quanto underscores. Números
|
|
|
+ são permitidos.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Todas as letras usadas em um nome de constante devem ser maiúsculas, enquanto todas
|
|
|
+ as palavras devem ser separadas por underscores.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Por exemplo, <constant>EMBED_SUPPRESS_EMBED_EXCEPTION</constant> é permitido
|
|
|
+ enquanto <constant>EMBED_SUPPRESSEMBEDEXCEPTION</constant> não.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Constantes devem ser definidas como membras de classe com o modificador "const".
|
|
|
+ Definir constantes em escopo global com a função "define" é permitido mas fortemente
|
|
|
+ desencorajado.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+ </sect1>
|
|
|
+
|
|
|
+ <sect1 id="coding-standard.coding-style">
|
|
|
+ <title>Estilo de Codificação</title>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.coding-style.php-code-demarcation">
|
|
|
+ <title>Demarcação de código PHP</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Código <acronym>PHP</acronym> deve sempre ser delimitado pelas tags na forma
|
|
|
+ completa, padrão do <acronym>PHP</acronym>:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+<?php
|
|
|
+
|
|
|
+?>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Tags reduzidas nunca não permitidas. Para arquivos que contenham somente código
|
|
|
+ <acronym>PHP</acronym>, a tag de fechamento deve sempre ser omitida (veja <link
|
|
|
+ linkend="coding-standard.php-file-formatting.general">a seção Geral</link>).
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.coding-style.strings">
|
|
|
+ <title>Strings</title>
|
|
|
+
|
|
|
+ <sect3 id="coding-standard.coding-style.strings.literals">
|
|
|
+ <title>Strings literais</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Quando uma string é literal (não contém substituição de variáveis), o apóstrofo
|
|
|
+ ou "aspa simples" deve sempre ser utilizado para demarcar a string:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+$a = 'Example String';
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="coding-standard.coding-style.strings.literals-containing-apostrophes">
|
|
|
+ <title>Strings literais contendo apóstrofos</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Quando uma string literal em si contém apóstrofos, é permitido demarcar a string
|
|
|
+ com aspas ou "aspas duplas". Isto é especialmente útil para sentenças
|
|
|
+ <constant>SQL</constant>:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+$sql = "SELECT `id`, `name` from `people` "
|
|
|
+ . "WHERE `name`='Fred' OR `name`='Susan'";
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Esta sintaxe é preferível a escapar os apóstrofos uma vez que é muito mais
|
|
|
+ legível.
|
|
|
+ </para>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="coding-standard.coding-style.strings.variable-substitution">
|
|
|
+ <title>Substituição de variáveis</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A substituição de variáveis é permitida utilizando qualquer uma destas formas:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+$greeting = "Hello $name, welcome back!";
|
|
|
+
|
|
|
+$greeting = "Hello {$name}, welcome back!";
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Por consistência, esta forma não é permitida:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+$greeting = "Hello ${name}, welcome back!";
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="coding-standard.coding-style.strings.string-concatenation">
|
|
|
+ <title>Concatenação de strings</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Strings devem ser concatenadas utilizando o operador ".". Um espaço deve sempre
|
|
|
+ ser adicionado antes e depois do operador "." para melhorar a legibilidade:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+$company = 'Zend' . ' ' . 'Technologies';
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Ao concatenar strings com o operador "." encoraja-se quebrar a expressão em
|
|
|
+ múltiplas linhas para facilitar a leitura. Nestes casos, cada linha sucessiva
|
|
|
+ deve ser indentada com espaços em branco de forma que o operador "." fique
|
|
|
+ alinhado com o operador "=":
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+$sql = "SELECT `id`, `name` FROM `people` "
|
|
|
+ . "WHERE `name` = 'Susan' "
|
|
|
+ . "ORDER BY `name` ASC ";
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.coding-style.arrays">
|
|
|
+ <title>Arrays</title>
|
|
|
+
|
|
|
+ <sect3 id="coding-standard.coding-style.arrays.numerically-indexed">
|
|
|
+ <title>Arrays numericamente indexados</title>
|
|
|
+
|
|
|
+ <para>Números negativos não são permitidos como índices.</para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Um array indexado deve iniciar com um número não-negativo. Entretanto, índices
|
|
|
+ iniciados em números diferentes de 0 são desencorajados.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Ao declarar arrays indexados com a função <type>Array</type>, um espaço deve ser
|
|
|
+ adicionado após cada vírgula delimitadora para aumentar a legibilidade:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+$sampleArray = array(1, 2, 3, 'Zend', 'Studio');
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ É permitido declarar arrays indexados em várias linhas utilizando o construtor
|
|
|
+ "array". Neste caso, cada linha sucessiva deve ser indentada com espaços de
|
|
|
+ forma que o começo de cada linha fique alinhado:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
|
|
|
+ $a, $b, $c,
|
|
|
+ 56.44, $d, 500);
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Alternativamente, o item inicial do array pode começar na linha seguinte. Neste
|
|
|
+ caso, ele deve ser indentado em um nível a mais que a linha que contém a
|
|
|
+ declaração do array e todas as linhas sucessivas devem ter a mesma indentação. O
|
|
|
+ parêntese de fechamento deve estar em uma linha a parte no mesmo nível de
|
|
|
+ indentação da linha que contém a declaração do array:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+$sampleArray = array(
|
|
|
+ 1, 2, 3, 'Zend', 'Studio',
|
|
|
+ $a, $b, $c,
|
|
|
+ 56.44, $d, 500,
|
|
|
+);
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Ao usar esta última declaração, encorajamos utilizar uma vírgula após o último
|
|
|
+ item do array. Isto minimiza o impacto de adicionar novos itens em linhas
|
|
|
+ sucessivas e ajuda a garantir que nenhum erro ocorra devido à ausência de uma
|
|
|
+ vírgula.
|
|
|
+ </para>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="coding-standard.coding-style.arrays.associative">
|
|
|
+ <title>Arrays associativos</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Ao declarar arrays associativos com o construtor <type>Array</type>, encoraja-se
|
|
|
+ quebrar a expressão em várias linhas. Neste caso, cada linha sucessiva deve ser
|
|
|
+ indentada com espaços em branco de forma que as chaves e os valores fiquem
|
|
|
+ alinhados:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+$sampleArray = array('firstKey' => 'firstValue',
|
|
|
+ 'secondKey' => 'secondValue');
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Alternativamente, o item inicial do array pode começar na linha seguinte. Neste
|
|
|
+ caso, ele deve ser indentado a um nível a mais que a linha contendo a declaração
|
|
|
+ do array e todas as linhas sucessivas devem ter a mesma indentação. O parêntese
|
|
|
+ de fechamento deve estar em uma linha própria, no mesmo nível de indentação da
|
|
|
+ linha que contém a declaração do array. Para legibilidade, os vários operadores
|
|
|
+ de atribuição "=>" devem ser espaçados de forma a ficarem alinhados.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+$sampleArray = array(
|
|
|
+ 'firstKey' => 'firstValue',
|
|
|
+ 'secondKey' => 'secondValue',
|
|
|
+);
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Ao utilizar esta última declaração, encorajamos utilizar uma vírgula após o
|
|
|
+ último item do array; isto minimiza o impacto de adicionar novos itens em linhas
|
|
|
+ sucessivas e ajuda a garantir que nenhum erro ocorra devido à ausência de uma
|
|
|
+ vírgula.
|
|
|
+ </para>
|
|
|
+ </sect3>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.coding-style.classes">
|
|
|
+ <title>Classes</title>
|
|
|
+
|
|
|
+ <sect3 id="coding-standard.coding-style.classes.declaration">
|
|
|
+ <title>Declaração de classe</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Classes devem ser nomeadas de acordo com a convenção de nomenclatura do Zend
|
|
|
+ Framework.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A chave deve ser sempre escrita na linha abaixo do nome da classe.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Toda classe deve ter um bloco de documentação em conformidade ao padrão do
|
|
|
+ PHPDocumentor.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Todo código em uma classe deve ser indentado com quatro espaços.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Apenas uma única classe é permitida em cada arquivo <acronym>PHP</acronym>.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A inserção de código adicional em arquivos de classe é permitida, mas
|
|
|
+ desencorajada. Em tais arquivos, duas linhas em branco devem separar a classe de
|
|
|
+ qualquer código <acronym>PHP</acronym> no arquivo.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A seguir, um exemplo de declaração de classe aceitável:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+/**
|
|
|
+ * Bloco de documentação aqui.
|
|
|
+ */
|
|
|
+class SampleClass
|
|
|
+{
|
|
|
+ // todo conteúdo de classe
|
|
|
+ // deve ser indentado quatro espaços
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Classes que estendem outras classes ou que implementam interfaces devem declarar
|
|
|
+ suas dependências na mesma linha, quando possível.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+class SampleClass extends FooAbstract implements BarInterface
|
|
|
+{
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Se estas operações fizerem com que o comprimento da linha exceda o <link
|
|
|
+ linkend="coding-standard.php-file-formatting.max-line-length">comprimento
|
|
|
+ máximo</link>, quebre a linha antes das palavras-chave "extends" e/ou
|
|
|
+ "implements", e indente tais linhas em mais um nível.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+class SampleClass
|
|
|
+ extends FooAbstract
|
|
|
+ implements BarInterface
|
|
|
+{
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Se a classe implementa múltiplas interfaces e a declaração excede o comprimento
|
|
|
+ máximo da linha, quebre após cada interface separada por vírgula e indente os
|
|
|
+ nomes das interfaces de forma a ficarem alinhados.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+class SampleClass
|
|
|
+ implements BarInterface,
|
|
|
+ BazInterface
|
|
|
+{
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="coding-standard.coding-style.classes.member-variables">
|
|
|
+ <title>Variáveis membras de classes</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Variáveis-membras devem ser nomeadas de acordo com as convenções de nomenclatura
|
|
|
+ de variáveis do Zend Framework.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Quaisquer variáveis declaradas em uma classe devem ser listadas no topo da
|
|
|
+ classe, acima da declaração de quaisquer métodos.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ O construtor <emphasis>var</emphasis> não é permitido. Variáveis-membras devem
|
|
|
+ sempre declarar sua visibilidade usando um dos modificadores
|
|
|
+ <property>private</property>, <property>protected</property> ou
|
|
|
+ <property>public</property>. Dar acesso direto a variáveis-membras declarando-as
|
|
|
+ como públicas é permitido mas desencorajado. Em vez disso, utilize métodos
|
|
|
+ acessores (set e get).
|
|
|
+ </para>
|
|
|
+ </sect3>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.coding-style.functions-and-methods">
|
|
|
+ <title>Funções e métodos</title>
|
|
|
+
|
|
|
+ <sect3 id="coding-standard.coding-style.functions-and-methods.declaration">
|
|
|
+ <title>Declaração de funções e métodos</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Funções devem ser nomeadas de acordo com as convenções de nomenclatura do Zend
|
|
|
+ Framework.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Métodos dentro de classes devem sempre declarar sua visibilidade usando um dos
|
|
|
+ modificadores <property>private</property>, <property>protected</property> ou
|
|
|
+ <property>public</property>.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Assim como ocorre com classes, a chave deve sempre ser escrita na linha abaixo
|
|
|
+ do nome da função. Espaços entre o nome da função e o parêntese de abertura para
|
|
|
+ os argumentos não são permitidos.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Funções em escopo global são fortemente desencorajadas.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A seguir, um exemplo de declaração aceitável de função em uma classe:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+/**
|
|
|
+ * Bloco de documentação aqui
|
|
|
+ */
|
|
|
+class Foo
|
|
|
+{
|
|
|
+ /**
|
|
|
+ * Bloco de documentação aqui
|
|
|
+ */
|
|
|
+ public function bar()
|
|
|
+ {
|
|
|
+ // todo conteúdo de função
|
|
|
+ // deve ser identado quatro espaços
|
|
|
+ }
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Quando a lista de argumentos exceder o <link
|
|
|
+ linkend="coding-standard.php-file-formatting.max-line-length">comprimento
|
|
|
+ máximo de linha</link> você pode introduzir quebras de linha. Argumentos
|
|
|
+ adicionais à função/método devem ser identados um nível a mais que o da
|
|
|
+ declaração da função/método. Uma quebra de linha deve ser colocada antes do
|
|
|
+ parêntese de fechamento de argumentos, que deve então ser colocado na mesma
|
|
|
+ linha da chave de abertura da função/método com uma espaço separando os dois, e
|
|
|
+ no mesmo nível de identação da declaração da função/método. A seguir, um exemplo
|
|
|
+ de tal situação:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+/**
|
|
|
+ * Bloco de documentação aqui
|
|
|
+ */
|
|
|
+class Foo
|
|
|
+{
|
|
|
+ /**
|
|
|
+ * Bloco de documentação aqui
|
|
|
+ */
|
|
|
+ public function bar($arg1, $arg2, $arg3,
|
|
|
+ $arg4, $arg5, $arg6
|
|
|
+ ) {
|
|
|
+ // todo conteúdo de função
|
|
|
+ // deve ser identado quatro espaços
|
|
|
+ }
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <note>
|
|
|
+ <para>
|
|
|
+ O único mecanismo de passagem de parâmetro permitido em uma declaração de
|
|
|
+ método é a passagem por referência.
|
|
|
+ </para>
|
|
|
+ </note>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+/**
|
|
|
+ * Bloco de documentação aqui
|
|
|
+ */
|
|
|
+class Foo
|
|
|
+{
|
|
|
+ /**
|
|
|
+ * Bloco de documentação aqui
|
|
|
+ */
|
|
|
+ public function bar(&$baz)
|
|
|
+ {}
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Passagem por referência em tempo de chamada é estritamente proibido.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ O valor de retorno não deve ser cercado por parênteses. Isto pode embaraçar a
|
|
|
+ legibilidade, além de quebrar o código caso um método seja modificado
|
|
|
+ posteriormente para retornar por referência.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+/**
|
|
|
+ * Bloco de documentação aqui
|
|
|
+ */
|
|
|
+class Foo
|
|
|
+{
|
|
|
+ /**
|
|
|
+ * ERRADO
|
|
|
+ */
|
|
|
+ public function bar()
|
|
|
+ {
|
|
|
+ return($this->bar);
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * CERTO
|
|
|
+ */
|
|
|
+ public function bar()
|
|
|
+ {
|
|
|
+ return $this->bar;
|
|
|
+ }
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="coding-standard.coding-style.functions-and-methods.usage">
|
|
|
+ <title>Uso de funções e métodos</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Argumentos de funções devem ser separados por um único espaço após a vírgula
|
|
|
+ delimitadora. A seguir, um exemplo de chamada aceitável de função que utiliza
|
|
|
+ três argumentos:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+threeArguments(1, 2, 3);
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Passagem por referência em tempo de chamada é estritamente proibido. Veja na
|
|
|
+ seção de declaração de funções a maneira apropriada de passar argumentos de
|
|
|
+ função por referência.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Ao passar arrays como argumentos para uma função, a chamada da função pode
|
|
|
+ incluir a indicação "array" e pode ser quebrada em múltiplas linhas para
|
|
|
+ aumentar a legibilidade. Em tais casos, as instruções para a escrita de arrays
|
|
|
+ ainda se aplicam:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+threeArguments(array(1, 2, 3), 2, 3);
|
|
|
+
|
|
|
+threeArguments(array(1, 2, 3, 'Zend', 'Studio',
|
|
|
+ $a, $b, $c,
|
|
|
+ 56.44, $d, 500), 2, 3);
|
|
|
+
|
|
|
+threeArguments(array(
|
|
|
+ 1, 2, 3, 'Zend', 'Studio',
|
|
|
+ $a, $b, $c,
|
|
|
+ 56.44, $d, 500
|
|
|
+), 2, 3);
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standard.coding-style.control-statements">
|
|
|
+ <title>Expressões de controle</title>
|
|
|
+
|
|
|
+ <sect3 id="coding-standard.coding-style.control-statements.if-else-elseif">
|
|
|
+ <title>If/Else/Elseif</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Expressões de controle baseadas nos construtores <emphasis>if</emphasis> e
|
|
|
+ <emphasis>elseif</emphasis> devem ter um único espaço antes do parêntese de
|
|
|
+ abertura do condicional e um único espaço depois do parêntese de fechamento.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Dentro das expressões condicionais entre os parênteses, os operadores devem ser
|
|
|
+ separados por espaços para maior legibilidade. Parênteses aninhados são
|
|
|
+ encorajados a fim de melhorar o agrupamento lógico de expressões condicionais
|
|
|
+ maiores.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A chave de abertura deve ser escrita na mesma linha da expressão condicional,
|
|
|
+ enquanto a chave de fechamento deve sempre ser escrita na sua própria linha.
|
|
|
+ Qualquer conteúdo dentro das chaves deve ser indentado utilizando quatro
|
|
|
+ espaços.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+if ($a != 2) {
|
|
|
+ $a = 2;
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Se a expressão condicional fizer com que a linha exceda o <link
|
|
|
+ linkend="coding-standard.php-file-formatting.max-line-length">comprimento
|
|
|
+ máximo</link> e possuir várias cláusulas você pode quebrar a condicional em
|
|
|
+ várias linhas. Em tais casos, quebre a linha antes de um operador lógico e
|
|
|
+ indente a linha de forma a ficar alinhada abaixo do primeiro caractere da
|
|
|
+ cláusula condicional. O parêntese de fechamento no condicional será então
|
|
|
+ colocado em uma linha junto à chave de abertura com um espaço separando os dois,
|
|
|
+ em um nível de indentação equivalente ao da expressão de controle de abertura.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+if (($a == $b)
|
|
|
+ && ($b == $c)
|
|
|
+ || (Foo::CONST == $d)
|
|
|
+) {
|
|
|
+ $a = $d;
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A intenção deste último formato de declaração é prevenir problemas ao adicionar
|
|
|
+ ou remover cláusulas da condicional durante revisões posteriores.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Para expressões "if" que incluem "elseif" ou "else", as convenções de formatação
|
|
|
+ são similares às do construtor "if". Os exemplos a seguir demonstram a
|
|
|
+ formatação apropriada para expressões "if" com construtores "else" e/ou
|
|
|
+ "elseif":
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+if ($a != 2) {
|
|
|
+ $a = 2;
|
|
|
+} else {
|
|
|
+ $a = 7;
|
|
|
+}
|
|
|
+
|
|
|
+if ($a != 2) {
|
|
|
+ $a = 2;
|
|
|
+} elseif ($a == 3) {
|
|
|
+ $a = 4;
|
|
|
+} else {
|
|
|
+ $a = 7;
|
|
|
+}
|
|
|
+
|
|
|
+if (($a == $b)
|
|
|
+ && ($b == $c)
|
|
|
+ || (Foo::CONST == $d)
|
|
|
+) {
|
|
|
+ $a = $d;
|
|
|
+} elseif (($a != $b)
|
|
|
+ || ($b != $c)
|
|
|
+) {
|
|
|
+ $a = $c;
|
|
|
+} else {
|
|
|
+ $a = $b;
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ O <acronym>PHP</acronym> permite que expressões sejam escritas sem chaves em
|
|
|
+ algumas circunstâncias. Este padrão de codificação, no entando, não faz
|
|
|
+ diferenciação alguma -- todas expressões "if", "elseif" ou "else" devem utilizar
|
|
|
+ chaves.
|
|
|
+ </para>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="coding-standards.coding-style.control-statements.switch">
|
|
|
+ <title>Switch</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Expressões de controle escritas com a expressão "switch" devem ter um único
|
|
|
+ espaço antes do parêntese de abertura da expressão condicional e após o
|
|
|
+ parêntese de fechamento.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Todo o conteúdo dentro da expressão "switch" deve ser indentado utilizando
|
|
|
+ quatro espaços e o conteúdo abaixo de cada expressão "case" deve ser indentado
|
|
|
+ utilizando quatro espaços adicionais.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+switch ($numPeople) {
|
|
|
+ case 1:
|
|
|
+ break;
|
|
|
+
|
|
|
+ case 2:
|
|
|
+ break;
|
|
|
+
|
|
|
+ default:
|
|
|
+ break;
|
|
|
+}
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ O construtor <property>default</property> nunca deve ser omitido de uma
|
|
|
+ expressão <property>switch</property>.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <note>
|
|
|
+ <para>
|
|
|
+ Em alguns casos é útil escrever uma expressão <property>case</property> que
|
|
|
+ recai sobre a próxima omitindo um <property>break</property> ou
|
|
|
+ <property>return</property>. Para diferenciar tais casos de bugs, qualquer
|
|
|
+ expressão <property>case</property> onde o <property>break</property> ou o
|
|
|
+ <property>return</property> sejam omitidos devem conter um comentário
|
|
|
+ indicando que a quebra foi intencionalmente omitida.
|
|
|
+ </para>
|
|
|
+ </note>
|
|
|
+ </sect3>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="coding-standards.inline-documentation">
|
|
|
+ <title>Documentação em linha de código</title>
|
|
|
+
|
|
|
+ <sect3 id="coding-standards.inline-documentation.documentation-format">
|
|
|
+ <title>Formato de documentação</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Todos blocos de documentação ("docblocks") devem ser compatíveis com o formato
|
|
|
+ phpDocumentor. Descrever o formato phpDocumentor está além do escopo deste
|
|
|
+ documento. Para mais informações, visite: <ulink
|
|
|
+ url="http://phpdoc.org/">http://phpdoc.org/</ulink>
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Todo arquivo de classe deve conter um docblock em nível de arquivo no topo de
|
|
|
+ cada arquivo e um docblock em nível de classe imediatamente acima da classe.
|
|
|
+ Exemplos de tais docblocks podem ser vistos abaixo.
|
|
|
+ </para>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="coding-standards.inline-documentation.files">
|
|
|
+ <title>Arquivos</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Todo arquivo que contém código <acronym>PHP</acronym> deve ter um docblock no
|
|
|
+ topo do arquivo contendo no mínimo estas tags do phpDocumentor:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+/**
|
|
|
+ * Descrição resumida do arquivo
|
|
|
+ *
|
|
|
+ * Descrição longa do arquivo (se houver)...
|
|
|
+ *
|
|
|
+ * LICENÇA: Informação sobre licença
|
|
|
+ *
|
|
|
+ * @category Zend
|
|
|
+ * @package Zend_Magic
|
|
|
+ * @subpackage Wand
|
|
|
+ * @copyright Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
|
|
|
+ * @license http://framework.zend.com/license BSD License
|
|
|
+ * @version $Id:$
|
|
|
+ * @link http://framework.zend.com/package/PackageName
|
|
|
+ * @since File available since Release 1.5.0
|
|
|
+*/
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A anotação <property>@category</property> deve ter o valor "Zend".
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A anotação <property>@package</property> deve ser utilizada e deve ser
|
|
|
+ equivalente ao nome do componente da classe contida no arquivo. Tipicamente, o
|
|
|
+ nome do componente possuirá apenas dois segmentos, o prefixo "Zend" e o nome do
|
|
|
+ componente.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A anotação <property>@subpackage</property> é opcional. Caso informada, deve ser
|
|
|
+ o nome do subcomponente menos o prefixo da classe. No exemplo acima, assume-se
|
|
|
+ que a classe no arquivo ou é "<classname>Zend_Magic_Wand</classname>" ou utiliza
|
|
|
+ tal nome de classe como parte de seu prefixo.
|
|
|
+ </para>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="coding-standards.inline-documentation.classes">
|
|
|
+ <title>Classes</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Toda classe deve ter um docblock que contenha no mínimo estas tags do
|
|
|
+ phpDocumentor:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+/**
|
|
|
+ * Descrição resumida da classe
|
|
|
+ *
|
|
|
+ * Descrição longa da classe (se houver)...
|
|
|
+ *
|
|
|
+ * @category Zend
|
|
|
+ * @package Zend_Magic
|
|
|
+ * @subpackage Wand
|
|
|
+ * @copyright Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
|
|
|
+ * @license http://framework.zend.com/license BSD License
|
|
|
+ * @version Release: @package_version@
|
|
|
+ * @link http://framework.zend.com/package/PackageName
|
|
|
+ * @since Class available since Release 1.5.0
|
|
|
+ * @deprecated Class deprecated in Release 2.0.0
|
|
|
+ */
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A anotação <property>@category</property> deve ter o valor "Zend".
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A anotação <property>@package</property> deve ser informada e deve ser
|
|
|
+ equivalente ao componente a que a classe pertence; tipicamente, terá apenas dois
|
|
|
+ segmentos: o prefixo "Zend" e o nome do componente.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ A anotação <property>@subpackage</property> é opcional. Caso informada, deve ser
|
|
|
+ o nome do subcomponente menos o prefixo da classe. No exemplo acima, assume-se
|
|
|
+ que a classe descrita ou é "<classname>Zend_Magic_Wand</classname>" ou utiliza
|
|
|
+ este nome como parte do seu prefixo.
|
|
|
+ </para>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="coding-standards.inline-documentation.functions">
|
|
|
+ <title>Funções</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Toda função, incluindo métodos de objetos, deve possuir um docblock que contenha
|
|
|
+ no mínimo:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <itemizedlist>
|
|
|
+ <listitem><para>Uma descrição da função</para></listitem>
|
|
|
+ <listitem><para>Todos os argumentos</para></listitem>
|
|
|
+ <listitem><para>Todos os possíveis valores de retorno</para></listitem>
|
|
|
+ </itemizedlist>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Não é necessário utilizar a tag "@access" já que o nível de acesso é conhecido
|
|
|
+ através do modificador "public", "private" ou "protected" utilizado na
|
|
|
+ declaração.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Se uma função ou método pode disparar uma exceção, utilize @throws para todas as
|
|
|
+ classes de exceção:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="php"><![CDATA[
|
|
|
+@throws exceptionclass [description]
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+ </sect2>
|
|
|
+ </sect1>
|
|
|
+</appendix>
|
|
|
+<!--
|
|
|
+vim:se ts=4 sw=4 et:
|
|
|
+-->
|
mauriciofauth