archived-doc-pt-br/appendices/userlandnaming.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 0ad6aa08fb58311737ae61515d12651d7f14626e Maintainer: ae Status: ready --><!-- CREDITS: diegopires,narigone,ae -->
<appendix xml:id="userlandnaming" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Guia de nomenclatura em espaço de usuário</title>
 <para>
  O seguinte guia tem como objetivo orientar em como escolher nome para identificadores
  em código PHP em espaço de usuário. Quando escolher nome para qualquer código que crie símbolos
  no escopo global, é importante levar em conta as seguintes
  orientações para prevenir que futuras versões do PHP entrem em conflito
  com o seus símbolos.
 </para>

 <section xml:id="userlandnaming.globalnamespace">
  <title>Escopo Global</title>
  <para>
   Aqui está uma visão geral de artefatos de código que acabam no escopo global:
  </para>

  <itemizedlist>
   <listitem><para>funções</para></listitem>
   <listitem><para>classes</para></listitem>
   <listitem><para>interfaces</para></listitem>
   <listitem><para>constantes (exceto constantes de classes)</para></listitem>
   <listitem>
    <para>variáveis definidas fora de funções e métodos</para>
   </listitem>
  </itemizedlist>
 </section>

 <section xml:id="userlandnaming.rules">
  <title>Regras</title>
  <para>
   A lista a seguir dá uma visão geral de quais direitos o projeto do PHP
   reserva para si, quando escolhe nomes para novos identificadores internos.
   O guia definitivo é
   <link xlink:href="&url.userlandnaming.cs;">PADRÕES DE CÓDIGO</link>:
  </para>

  <itemizedlist>
   <listitem>
    <para>
     PHP detém o escopo de alto nível, mas tenta encontrar nomes descritivos
     decentes e evita qualquer conflito óbvio.
    </para>
   </listitem>
   <listitem>
    <para>
     Nomes de funções usam sublinhado (_) entre palavras, enquanto nomes de classe usam
     a notação <literal>camelCase</literal> e
     <literal>PascalCase</literal>.
    </para>
   </listitem>
   <listitem>
    <para>
     O PHP prefixará quaisquer símbolos globais de uma extensão com o nome da
     extensão (no passado, existiam várias exceções
     à essa regra). Exemplos:
    </para>

    <itemizedlist>
     <listitem><para><function>curl_close</function></para></listitem>
     <listitem><para><function>mysql_query</function></para></listitem>
     <listitem><para>PREG_SPLIT_DELIM_CAPTURE</para></listitem>
     <listitem><para>new DOMDocument()</para></listitem>
     <listitem>
      <para>
       <function>strpos</function> (exemplo de um erro do passado)
      </para>
     </listitem>
     <listitem><para>new SplFileObject()</para></listitem>
    </itemizedlist>
   </listitem>
   <listitem>
    <para>
     Iteradores e Exceções são, no entanto, simplesmente sufixados com
     "<literal>Iterator</literal>" e "<literal>Exception</literal>".
     Exemplos:
    </para>
    <itemizedlist>
     <listitem><para><classname>ArrayIterator</classname></para></listitem>
     <listitem><para><classname>LogicException</classname></para></listitem>
    </itemizedlist>
   </listitem>
   <listitem>
    <para>
     O PHP reserva todos os símbolos começando com <literal>__</literal>
     como mágicos. É recomendado que você não crie símbolos começando com
     <literal>__</literal> a não ser que
     você queira usar a funcionalidade mágica documentada. Exemplos:
    </para>
    <itemizedlist>
     <listitem><para><link linkend="object.get">__get</link></para></listitem>
     <listitem><para><function>__autoload</function></para></listitem>
    </itemizedlist>
   </listitem>
  </itemizedlist>
 </section>

 <section xml:id="userlandnaming.tips">
  <title>Dicas</title>
  <para>
   Para escrever código que não sofrerá problemas no futuro, é recomendado que não
   sejam incluídas variáveis, funções ou classes no espaço global. Isto
   evitará colisões de nome com código de terceiros assim como
   futuros acréscimos à linguagem.
  </para>
  <para>
   Uma forma de prevenir colisões de nomes em funções e classes é
   colocá-las em seus próprios
   <link linkend="language.namespaces">namespaces</link>.
  </para>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php

namespace MyProject;

function my_function() {
    return true;
}

\MyProject\my_function();
]]>
   </programlisting>
  </informalexample>
  <para>
   Os namespaces já usados ainda precisam ser rastreados, mas uma vez
   decidido o uso de um namespace, podem ser adicionadas funções e
   classes a ele sem novas preocupações com conflitos.
  </para>
  <para>
   Também é considerada uma boa prática limitar o número de variáveis alocadas
   no escopo global de forma a evitar colisões de nome com código
   de terceiros.
  </para>
  <note>
   <title>Escopo de variáveis</title>
   <para>
    Por causa das <link linkend="language.variables.scope">regras de escopo</link> do PHP,
    as variáveis definidas dentro de funções e métodos não estão no escopo global
    e não podem conflitar com variáveis definidas nesse escopo.
   </para>
  </note>
 </section>

</appendix>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->