userlandnaming.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 0ad6aa08fb58311737ae61515d12651d7f14626e Maintainer: shein Status: ready -->
<!-- Reviewed: yes Maintainer: rjhdby -->
<!-- $Revision$ -->
<appendix xml:id="userlandnaming" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Руководство по именованию</title>
 <para>
  Этот документ содержит советы по выбору имён для идентификаторов PHP-кода.
  При выборе имён для кода, создающего идентификаторы в глобальном пространстве
  имён, важно принимать во внимание это руководство, чтобы избежать
  коллизий имён из будущих версий PHP с вашим кодом.
 </para>

 <section xml:id="userlandnaming.globalnamespace">
  <title>Глобальное пространство имён</title>
  <para>
   Обзор конструкций, создающих идентификаторы в глобальном пространстве имён.
  </para>

  <itemizedlist>
   <listitem><para>функции</para></listitem>
   <listitem><para>классы</para></listitem>
   <listitem><para>интерфейсы</para></listitem>
   <listitem><para>константы (не константы классов)</para></listitem>
   <listitem>
    <para>переменные, объявленные вне функций/методов</para>
   </listitem>
  </itemizedlist>
 </section>

 <section xml:id="userlandnaming.rules">
  <title>Правила</title>
  <para>
   Следующий список правил даёт обзор прав именования, которые проект PHP
   оставляет себе при выборе новых идентификаторов. Полным руководством
   является официальный "<link xlink:href="&url.userlandnaming.cs;">Стандарт
   написания кода</link>":
  </para>

  <itemizedlist>
   <listitem>
    <para>
     PHP владеет глобальным пространством имён, но старается находить
     хорошие описательные имена и избегать любых очевидных коллизий.
    </para>
   </listitem>
   <listitem>
    <para>
     Имена функций используют подчёркивания между словами, а имена классов
     используют как <literal>camelCase</literal>, так и <literal>PascalCase</literal>.
    </para>
   </listitem>
   <listitem>
    <para>
     PHP добавляет префикс к глобальным именам, принадлежащим модулю
     с именем этого модуля. В прошлом было множество исключений из этого
     правила, например:
    </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> (пример исключения, допущенного в прошлом)
      </para>
     </listitem>
     <listitem><para>new SplFileObject()</para></listitem>
    </itemizedlist>
   </listitem>
   <listitem>
    <para>
     Тем не менее, итераторы и исключения просто получают постфиксы
     "<literal>Iterator</literal>" и "<literal>Exception</literal>".
     Примеры:
    </para>
    <itemizedlist>
     <listitem><para><classname>ArrayIterator</classname></para></listitem>
     <listitem><para><classname>LogicException</classname></para></listitem>
    </itemizedlist>
   </listitem>
   <listitem>
    <para>
     PHP резервирует все идентификаторы, начинающиеся с <literal>__</literal>
     как магические. Рекомендуется не создавать идентификаторы, начинающиеся
     с <literal>__</literal>, кроме как с целью использовать документированную
     магическую функциональность. Примеры:
    </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>Советы</title>
  <para>
   Для написания кода с прицелом на будущее, рекомендуется не помещать
   много переменных, функций и классов в глобальное пространство имён. Это поможет
   избежать конфликтов со сторонними библиотеками, а также возможные будущие дополнения к языку.
   которым может быть добавлен в будущем.
  </para>

  <para>
   Одним из самых распространённых способов избежать конфликтов классов и функций,
   это определять их в своём собственном, отдельном
   <link linkend="language.namespaces">пространстве имён</link>.
  </para>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php

namespace MyProject;

function my_function() {
    return true;
}

\MyProject\my_function();
]]>
   </programlisting>
  </informalexample>
  <para>
   Вам всё ещё нужно отслеживать уже используемые пространства имён, но
   единожды определившись с ним, вы можете добавить в него все функции и классы,
   не думая о возможных проблемах.
  </para>
  <para>
   Максимально ограничивать количество переменных в глобальном пространстве имён
   является хорошей практикой. Это позволит минимизировать возможность конфликтов
   со сторонним кодом, который вы решите добавить в свой проект.
  </para>
  <note>
   <title>Область видимости переменных</title>
   <para>
    Согласно правилам <link linkend="language.variables.scope">области видимости</link>
    в PHP переменные, определённые внутри функций и классов не могут
    конфликтовать с переменными, заданными в глобальной области видимости.
   </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
-->