1 <appendix id="coding-standard">
2 <title>Стандарт написання PHP коду в Zend Framework</title>
3 <sect1 id="coding-standard.overview">
6 <sect2 id="coding-standard.overview.scope">
7 <title>Сфера застосування</title>
10 Цей документ надає вказівки щодо форматування коду та документації для розробників
11 та команд які роблять свій вклад в розробку Zend Framework. Багато розробників
12 що використовують Zend Framework також знаходять корисним слідувати
13 цим стандартам щоб писати свій код у відповідності до всього коду Zend Framework.
14 Варто зазначити що докладено великих зусиль щоб як найбільш повно описати стандарти кодування.
18 Примітка: Sometimes developers consider the establishment of a standard more
19 important than what that standard actually suggests at the most detailed
20 level of design. Інколи розробники надають впровадженню стандарту важливішого
21 значення ніж те, що стандарт дійсно пропонує, на найбільш деталізованому
22 рівні розробки. Вказівки в стандартах кодування Zend Framework захоплюють
23 практичні підходи що добре себе зарекомендували в проекті розробки Zend Framework.
24 Дозволяється модифікувати ці стандарти або використовувати їх в незмінному
25 стані у відповідності до положень нашої
26 <ulink url="http://framework.zend.com/license">ліцензії</ulink>.
30 Теми що висвітлюються в стандартах кодування Zend Framework включають:
33 <para>Форматування <acronym>PHP</acronym> файлів</para>
37 <para>Принципи іменування</para>
41 <para>Стиль написання коду</para>
45 <para>Вбудована документація</para>
51 <sect2 id="coding-standard.overview.goals">
55 Дотримання стандартів написання коду є важливим для будь якого проекту,
56 зокрема коли над одним проектом працюють кілька розробників.
57 Стандарти написання коду забезпечують високу якість,
58 меншу кількість помилок, та легкий супровід коду.
63 <sect1 id="coding-standard.php-file-formatting">
64 <title>Форматування PHP файлів</title>
66 <sect2 id="coding-standard.php-file-formatting.general">
67 <title>Загальні положення</title>
70 Заборонено ставити закриваючий тег ("?>") для файлів що містять виключно
71 <acronym>PHP</acronym> код. Закриваючий тег необов'язковий для <acronym>PHP</acronym>,
72 та його відсутність допомагає уникнути випадкового попадання у відповідь сервера
73 пробілу що опинився в кінці файлу.
78 <emphasis>Важливо</emphasis>: Включення додаткового бінарного коду як це дозволено при
79 використанні <code>__HALT_COMPILER()</code> заборонено для всіх <acronym>PHP</acronym>
80 файлів в проекті Zend framework та похідних файлах. Використання такої можливості
81 дозволено лише для деяких сценаріїв встановлення.
87 <sect2 id="coding-standard.php-file-formatting.indentation">
88 <title>Відступи</title>
90 <para>Використовувати відступ в 4 пробіли, без табуляції.</para>
93 <sect2 id="coding-standard.php-file-formatting.max-line-length">
94 <title>Максимальна довжина рядка</title>
97 Дотримуватися довжини рядка в 80 символів, тобто розробники повинні намагатись тримати
98 код настільки близько до 80-ої колонки наскільки це практично можливо.
99 Проте, довші рядки дозволені. Максимальна довжина будь-якого рядка <acronym>PHP</acronym> коду
100 не повинна перевищувати 120 символів.
104 <sect2 id="coding-standard.php-file-formatting.line-termination">
105 <title>Завершення рядків</title>
108 Завершення рядка в стандартний спосіб для текстових файлів Unix. Рядки повинні завершуватися
109 через переведення рядка (LF). Переведення рядка представлено десятковим кодом 10,
110 та шістнадцятковим 0x0A.
114 Примітка: Не використовувати повернення каретки (CR) у відповідності до ОС Apple (0x0D) або
115 комбінацію повернення каретки - переведення рядка (CRLF)
116 що є стандартом для ОС Windows (0x0D, 0x0A).
121 <sect1 id="coding-standard.naming-conventions">
122 <title>Принципи іменування</title>
124 <sect2 id="coding-standard.naming-conventions.classes">
128 Zend Framework standardizes on a class naming convention whereby the names of the
129 classes directly map to the directories in which they are stored. The root level
130 directory of Zend Framework's standard library is the "Zend/" directory, whereas
131 the root level directory of Zend Framework's extras library is the "ZendX/"
132 directory. All Zend Framework classes are stored hierarchically under these root
137 Class names may only contain alphanumeric characters. Numbers are permitted
138 in class names but are discouraged in most cases. Underscores are only permitted in
139 place of the path separator; the filename "<filename>Zend/Db/Table.php</filename>"
140 must map to the class name "<classname>Zend_Db_Table</classname>".
144 If a class name is comprised of more than one word, the first letter of each new
145 word must be capitalized. Successive capitalized letters are not allowed, e.g.
146 a class "Zend_PDF" is not allowed while "<classname>Zend_Pdf</classname>" is
151 These conventions define a pseudo-namespace mechanism for Zend Framework. Zend
152 Framework will adopt the <acronym>PHP</acronym> namespace feature when it becomes
153 available and is feasible for our developers to use in their applications.
157 See the class names in the standard and extras libraries for examples of this
158 classname convention.
163 <emphasis>Important</emphasis>: Code that must be deployed alongside
164 Zend Framework libraries but is not part of the standard or extras libraries
165 (e.g. application code or libraries that are not distributed by Zend) must
166 never start with "Zend_" or "ZendX_".
171 <sect2 id="coding-standard.naming-conventions.abstracts">
172 <title>Abstract Classes</title>
175 In general, abstract classes follow the same conventions as <link
176 linkend="coding-standard.naming-conventions.classes">classes</link>,
177 with one additional rule: abstract class names must end in the term, "Abstract",
178 and that term must not be preceded by an underscore. As an example,
179 <classname>Zend_Controller_Plugin_Abstract</classname> is considered an
180 invalid name, but <classname>Zend_Controller_PluginAbstract</classname> or
181 <classname>Zend_Controller_Plugin_PluginAbstract</classname> would be valid
187 This naming convention is new with version 1.9.0 of Zend Framework. Classes
188 that pre-date that version may not follow this rule, but will be renamed in
189 the future in order to comply.
194 <sect2 id="coding-standard.naming-conventions.interfaces">
195 <title>Interfaces</title>
198 In general, interfaces follow the same conventions as <link
199 linkend="coding-standard.naming-conventions.classes">classes</link>,
200 with one additional rule: interface names may optionally end in the term,
201 "Interface", but that term must not be preceded by an underscore. As an example,
202 <classname>Zend_Controller_Plugin_Interface</classname> is considered an
203 invalid name, but <classname>Zend_Controller_PluginInterface</classname> or
204 <classname>Zend_Controller_Plugin_PluginInterface</classname> would be valid
209 While this rule is not required, it is strongly recommended, as it provides a
210 good visual cue to developers as to which files contain interfaces rather than
216 This naming convention is new with version 1.9.0 of Zend Framework. Classes
217 that pre-date that version may not follow this rule, but will be renamed in
218 the future in order to comply.
223 <sect2 id="coding-standard.naming-conventions.filenames">
224 <title>Filenames</title>
227 For all other files, only alphanumeric characters, underscores, and the dash
228 character ("-") are permitted. Spaces are strictly prohibited.
232 Any file that contains <acronym>PHP</acronym> code should end with the extension
233 "<filename>.php</filename>", with the notable exception of view scripts. The
234 following examples show acceptable filenames for Zend Framework classes:
237 <programlisting language="php"><![CDATA[
240 Zend/Controller/Front.php
242 Zend/View/Helper/FormRadio.php
246 File names must map to class names as described above.
250 <sect2 id="coding-standard.naming-conventions.functions-and-methods">
251 <title>Functions and Methods</title>
254 Function names may only contain alphanumeric characters. Underscores are not
255 permitted. Numbers are permitted in function names but are discouraged in most
260 Function names must always start with a lowercase letter. When a function name
261 consists of more than one word, the first letter of each new word must be
262 capitalized. This is commonly called "camelCase" formatting.
266 Verbosity is generally encouraged. Function names should be as verbose as is
267 practical to fully describe their purpose and behavior.
271 These are examples of acceptable names for functions:
274 <programlisting language="php"><![CDATA[
283 For object-oriented programming, accessors for instance or static variables should
284 always be prefixed with "get" or "set". In implementing design patterns, such as the
285 singleton or factory patterns, the name of the method should contain the pattern
286 name where practical to more thoroughly describe behavior.
290 For methods on objects that are declared with the "private" or "protected" modifier,
291 the first character of the method name must be an underscore. This is the only
292 acceptable application of an underscore in a method name. Methods declared "public"
293 should never contain an underscore.
297 Functions in the global scope (a.k.a "floating functions") are permitted but
298 discouraged in most cases. Consider wrapping these functions in a static class.
302 <sect2 id="coding-standard.naming-conventions.variables">
303 <title>Variables</title>
306 Variable names may only contain alphanumeric characters. Underscores are not
307 permitted. Numbers are permitted in variable names but are discouraged in most
312 For instance variables that are declared with the "private" or "protected" modifier,
313 the first character of the variable name must be a single underscore. This is the
314 only acceptable application of an underscore in a variable name. Member variables
315 declared "public" should never start with an underscore.
319 As with function names (see section 3.3) variable names must always start with a
320 lowercase letter and follow the "camelCaps" capitalization convention.
324 Verbosity is generally encouraged. Variables should always be as verbose as
325 practical to describe the data that the developer intends to store in them. Terse
326 variable names such as "<varname>$i</varname>" and "<varname>$n</varname>" are
327 discouraged for all but the smallest loop contexts. If a loop contains more than
328 20 lines of code, the index variables should have more descriptive names.
332 <sect2 id="coding-standard.naming-conventions.constants">
333 <title>Constants</title>
336 Constants may contain both alphanumeric characters and underscores. Numbers are
337 permitted in constant names.
341 All letters used in a constant name must be capitalized, while all words in a
342 constant name must be separated by underscore characters.
346 For example, <constant>EMBED_SUPPRESS_EMBED_EXCEPTION</constant> is permitted but
347 <constant>EMBED_SUPPRESSEMBEDEXCEPTION</constant> is not.
351 Constants must be defined as class members with the "const" modifier. Defining
352 constants in the global scope with the "define" function is permitted but strongly
358 <sect1 id="coding-standard.coding-style">
359 <title>Coding Style</title>
361 <sect2 id="coding-standard.coding-style.php-code-demarcation">
362 <title>PHP Code Demarcation</title>
365 <acronym>PHP</acronym> code must always be delimited by the full-form, standard
366 <acronym>PHP</acronym> tags:
369 <programlisting language="php"><![CDATA[
376 Short tags are never allowed. For files containing only <acronym>PHP</acronym>
377 code, the closing tag must always be omitted (See <link
378 linkend="coding-standard.php-file-formatting.general">General standards</link>).
382 <sect2 id="coding-standard.coding-style.strings">
383 <title>Strings</title>
385 <sect3 id="coding-standard.coding-style.strings.literals">
386 <title>String Literals</title>
389 When a string is literal (contains no variable substitutions), the apostrophe or
390 "single quote" should always be used to demarcate the string:
393 <programlisting language="php"><![CDATA[
394 $a = 'Example String';
398 <sect3 id="coding-standard.coding-style.strings.literals-containing-apostrophes">
399 <title>String Literals Containing Apostrophes</title>
402 When a literal string itself contains apostrophes, it is permitted to demarcate
403 the string with quotation marks or "double quotes". This is especially useful
404 for <constant>SQL</constant> statements:
407 <programlisting language="php"><![CDATA[
408 $sql = "SELECT `id`, `name` from `people` "
409 . "WHERE `name`='Fred' OR `name`='Susan'";
413 This syntax is preferred over escaping apostrophes as it is much easier to read.
417 <sect3 id="coding-standard.coding-style.strings.variable-substitution">
418 <title>Variable Substitution</title>
421 Variable substitution is permitted using either of these forms:
424 <programlisting language="php"><![CDATA[
425 $greeting = "Hello $name, welcome back!";
427 $greeting = "Hello {$name}, welcome back!";
431 For consistency, this form is not permitted:
434 <programlisting language="php"><![CDATA[
435 $greeting = "Hello ${name}, welcome back!";
439 <sect3 id="coding-standard.coding-style.strings.string-concatenation">
440 <title>String Concatenation</title>
443 Strings must be concatenated using the "." operator. A space must always
444 be added before and after the "." operator to improve readability:
447 <programlisting language="php"><![CDATA[
448 $company = 'Zend' . ' ' . 'Technologies';
452 When concatenating strings with the "." operator, it is encouraged to
453 break the statement into multiple lines to improve readability. In these
454 cases, each successive line should be padded with white space such that the
455 "."; operator is aligned under the "=" operator:
458 <programlisting language="php"><![CDATA[
459 $sql = "SELECT `id`, `name` FROM `people` "
460 . "WHERE `name` = 'Susan' "
461 . "ORDER BY `name` ASC ";
466 <sect2 id="coding-standard.coding-style.arrays">
467 <title>Arrays</title>
469 <sect3 id="coding-standard.coding-style.arrays.numerically-indexed">
470 <title>Numerically Indexed Arrays</title>
472 <para>Negative numbers are not permitted as indices.</para>
475 An indexed array may start with any non-negative number, however
476 all base indices besides 0 are discouraged.
480 When declaring indexed arrays with the <type>Array</type> function, a trailing
481 space must be added after each comma delimiter to improve readability:
484 <programlisting language="php"><![CDATA[
485 $sampleArray = array(1, 2, 3, 'Zend', 'Studio');
489 It is permitted to declare multi-line indexed arrays using the "array"
490 construct. In this case, each successive line must be padded with spaces such
491 that beginning of each line is aligned:
494 <programlisting language="php"><![CDATA[
495 $sampleArray = array(1, 2, 3, 'Zend', 'Studio',
501 Alternately, the initial array item may begin on the following line. If so,
502 it should be padded at one indentation level greater than the line containing
503 the array declaration, and all successive lines should have the same
504 indentation; the closing paren should be on a line by itself at the same
505 indentation level as the line containing the array declaration:
508 <programlisting language="php"><![CDATA[
509 $sampleArray = array(
510 1, 2, 3, 'Zend', 'Studio',
517 When using this latter declaration, we encourage using a trailing comma for
518 the last item in the array; this minimizes the impact of adding new items on
519 successive lines, and helps to ensure no parse errors occur due to a missing
524 <sect3 id="coding-standard.coding-style.arrays.associative">
525 <title>Associative Arrays</title>
528 When declaring associative arrays with the <type>Array</type> construct,
529 breaking the statement into multiple lines is encouraged. In this case, each
530 successive line must be padded with white space such that both the keys and the
534 <programlisting language="php"><![CDATA[
535 $sampleArray = array('firstKey' => 'firstValue',
536 'secondKey' => 'secondValue');
540 Alternately, the initial array item may begin on the following line. If so,
541 it should be padded at one indentation level greater than the line containing
542 the array declaration, and all successive lines should have the same
543 indentation; the closing paren should be on a line by itself at the same
544 indentation level as the line containing the array declaration. For
545 readability, the various "=>" assignment operators should be padded such that
549 <programlisting language="php"><![CDATA[
550 $sampleArray = array(
551 'firstKey' => 'firstValue',
552 'secondKey' => 'secondValue',
557 When using this latter declaration, we encourage using a trailing comma for
558 the last item in the array; this minimizes the impact of adding new items on
559 successive lines, and helps to ensure no parse errors occur due to a missing
565 <sect2 id="coding-standard.coding-style.classes">
566 <title>Classes</title>
568 <sect3 id="coding-standard.coding-style.classes.declaration">
569 <title>Class Declaration</title>
572 Classes must be named according to Zend Framework's naming conventions.
576 The brace should always be written on the line underneath the class name.
580 Every class must have a documentation block that conforms to the PHPDocumentor
585 All code in a class must be indented with four spaces.
589 Only one class is permitted in each <acronym>PHP</acronym> file.
593 Placing additional code in class files is permitted but discouraged.
594 In such files, two blank lines must separate the class from any additional
595 <acronym>PHP</acronym> code in the class file.
599 The following is an example of an acceptable class declaration:
602 <programlisting language="php"><![CDATA[
604 * Documentation Block Here
608 // all contents of class
609 // must be indented four spaces
614 Classes that extend other classes or which implement interfaces should
615 declare their dependencies on the same line when possible.
618 <programlisting language="php"><![CDATA[
619 class SampleClass extends FooAbstract implements BarInterface
625 If as a result of such declarations, the line length exceeds the <link
626 linkend="coding-standard.php-file-formatting.max-line-length">maximum line
627 length</link>, break the line before the "extends" and/or "implements"
628 keywords, and pad those lines by one indentation level.
631 <programlisting language="php"><![CDATA[
634 implements BarInterface
640 If the class implements multiple interfaces and the declaration exceeds the
641 maximum line length, break after each comma separating the interfaces, and
642 indent the interface names such that they align.
645 <programlisting language="php"><![CDATA[
647 implements BarInterface,
654 <sect3 id="coding-standard.coding-style.classes.member-variables">
655 <title>Class Member Variables</title>
658 Member variables must be named according to Zend Framework's variable naming
663 Any variables declared in a class must be listed at the top of the class, above
664 the declaration of any methods.
668 The <emphasis>var</emphasis> construct is not permitted. Member variables always
669 declare their visibility by using one of the <property>private</property>,
670 <property>protected</property>, or <property>public</property> modifiers. Giving
671 access to member variables directly by declaring them as public is permitted but
672 discouraged in favor of accessor methods (set & get).
677 <sect2 id="coding-standard.coding-style.functions-and-methods">
678 <title>Functions and Methods</title>
680 <sect3 id="coding-standard.coding-style.functions-and-methods.declaration">
681 <title>Function and Method Declaration</title>
684 Functions must be named according to Zend Framework's function naming
689 Methods inside classes must always declare their visibility by using
690 one of the <property>private</property>, <property>protected</property>,
691 or <property>public</property> modifiers.
695 As with classes, the brace should always be written on the line underneath the
696 function name. Space between the function name and the opening parenthesis for
697 the arguments is not permitted.
701 Functions in the global scope are strongly discouraged.
705 The following is an example of an acceptable function declaration in a class:
708 <programlisting language="php"><![CDATA[
710 * Documentation Block Here
715 * Documentation Block Here
717 public function bar()
719 // all contents of function
720 // must be indented four spaces
726 In cases where the argument list exceeds the <link
727 linkend="coding-standard.php-file-formatting.max-line-length">maximum line
728 length</link>, you may introduce line breaks. Additional arguments to the
729 function or method must be indented one additional level beyond the function
730 or method declaration. A line break should then occur before the closing
731 argument paren, which should then be placed on the same line as the opening
732 brace of the function or method with one space separating the two, and at the
733 same indentation level as the function or method declaration. The following is
734 an example of one such situation:
737 <programlisting language="php"><![CDATA[
739 * Documentation Block Here
744 * Documentation Block Here
746 public function bar($arg1, $arg2, $arg3,
749 // all contents of function
750 // must be indented four spaces
757 <emphasis>Note</emphasis>: Pass-by-reference is the only parameter passing
758 mechanism permitted in a method declaration.
762 <programlisting language="php"><![CDATA[
764 * Documentation Block Here
769 * Documentation Block Here
771 public function bar(&$baz)
777 Call-time pass-by-reference is strictly prohibited.
781 The return value must not be enclosed in parentheses. This can hinder
782 readability, in additional to breaking code if a method is later changed to
786 <programlisting language="php"><![CDATA[
788 * Documentation Block Here
795 public function bar()
803 public function bar()
811 <sect3 id="coding-standard.coding-style.functions-and-methods.usage">
812 <title>Function and Method Usage</title>
815 Function arguments should be separated by a single trailing space after the
816 comma delimiter. The following is an example of an acceptable invocation of a
817 function that takes three arguments:
820 <programlisting language="php"><![CDATA[
821 threeArguments(1, 2, 3);
825 Call-time pass-by-reference is strictly prohibited. See the function
826 declarations section for the proper way to pass function arguments by-reference.
830 In passing arrays as arguments to a function, the function call may include the
831 "array" hint and may be split into multiple lines to improve readability. In
832 such cases, the normal guidelines for writing arrays still apply:
835 <programlisting language="php"><![CDATA[
836 threeArguments(array(1, 2, 3), 2, 3);
838 threeArguments(array(1, 2, 3, 'Zend', 'Studio',
840 56.44, $d, 500), 2, 3);
842 threeArguments(array(
843 1, 2, 3, 'Zend', 'Studio',
851 <sect2 id="coding-standard.coding-style.control-statements">
852 <title>Control Statements</title>
854 <sect3 id="coding-standard.coding-style.control-statements.if-else-elseif">
855 <title>If/Else/Elseif</title>
858 Control statements based on the <emphasis>if</emphasis> and
859 <emphasis>elseif</emphasis> constructs must have a single space before the
860 opening parenthesis of the conditional and a single space after the closing
865 Within the conditional statements between the parentheses, operators must be
866 separated by spaces for readability. Inner parentheses are encouraged to improve
867 logical grouping for larger conditional expressions.
871 The opening brace is written on the same line as the conditional statement. The
872 closing brace is always written on its own line. Any content within the braces
873 must be indented using four spaces.
876 <programlisting language="php"><![CDATA[
883 If the conditional statement causes the line length to exceed the <link
884 linkend="coding-standard.php-file-formatting.max-line-length">maximum line
885 length</link> and has several clauses, you may break the conditional into
886 multiple lines. In such a case, break the line prior to a logic operator, and
887 pad the line such that it aligns under the first character of the conditional
888 clause. The closing paren in the conditional will then be placed on a line with
889 the opening brace, with one space separating the two, at an indentation level
890 equivalent to the opening control statement.
893 <programlisting language="php"><![CDATA[
896 || (Foo::CONST == $d)
903 The intention of this latter declaration format is to prevent issues when
904 adding or removing clauses from the conditional during later revisions.
908 For "if" statements that include "elseif" or "else", the formatting conventions
909 are similar to the "if" construct. The following examples demonstrate proper
910 formatting for "if" statements with "else" and/or "elseif" constructs:
913 <programlisting language="php"><![CDATA[
930 || (Foo::CONST == $d)
943 <acronym>PHP</acronym> allows statements to be written without braces in some
944 circumstances. This coding standard makes no differentiation- all "if",
945 "elseif" or "else" statements must use braces.
949 <sect3 id="coding-standards.coding-style.control-statements.switch">
950 <title>Switch</title>
953 Control statements written with the "switch" statement must have a single space
954 before the opening parenthesis of the conditional statement and after the
959 All content within the "switch" statement must be indented using four spaces.
960 Content under each "case" statement must be indented using an additional four
964 <programlisting language="php"><![CDATA[
965 switch ($numPeople) {
978 The construct <property>default</property> should never be omitted from a
979 <property>switch</property> statement.
984 <emphasis>Note</emphasis>: It is sometimes useful to write a
985 <property>case</property> statement which falls through to the next case by
986 not including a <property>break</property> or <property>return</property>
987 within that case. To distinguish these cases from bugs, any
988 <property>case</property> statement where <property>break</property> or
989 <property>return</property> are omitted should contain a comment indicating
990 that the break was intentionally omitted.
996 <sect2 id="coding-standards.inline-documentation">
997 <title>Inline Documentation</title>
999 <sect3 id="coding-standards.inline-documentation.documentation-format">
1000 <title>Documentation Format</title>
1003 All documentation blocks ("docblocks") must be compatible with the phpDocumentor
1004 format. Describing the phpDocumentor format is beyond the scope of this
1005 document. For more information, visit: <ulink
1006 url="http://phpdoc.org/">http://phpdoc.org/</ulink>
1010 All class files must contain a "file-level" docblock at the top of each file and
1011 a "class-level" docblock immediately above each class. Examples of such
1012 docblocks can be found below.
1016 <sect3 id="coding-standards.inline-documentation.files">
1017 <title>Files</title>
1020 Every file that contains <acronym>PHP</acronym> code must have a docblock at
1021 the top of the file that contains these phpDocumentor tags at a minimum:
1024 <programlisting language="php"><![CDATA[
1026 * Short description for file
1028 * Long description for file (if any)...
1030 * LICENSE: Some license information
1033 * @package Zend_Magic
1035 * @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
1036 * @license http://framework.zend.com/license BSD License
1038 * @link http://framework.zend.com/package/PackageName
1039 * @since File available since Release 1.5.0
1041 ]]></programlisting>
1044 The <property>@category</property> annotation must have a value of "Zend".
1048 The <property>@package</property> annotation must be assigned, and should be
1049 equivalent to the component name of the class contained in the file; typically,
1050 this will only have two segments, the "Zend" prefix, and the component name.
1054 The <property>@subpackage</property> annotation is optional. If provided, it
1055 should be the subcomponent name, minus the class prefix. In the example above,
1056 the assumption is that the class in the file is either
1057 "<classname>Zend_Magic_Wand</classname>", or uses that classname as part of its
1062 <sect3 id="coding-standards.inline-documentation.classes">
1063 <title>Classes</title>
1066 Every class must have a docblock that contains these phpDocumentor tags at a
1070 <programlisting language="php"><![CDATA[
1072 * Short description for class
1074 * Long description for class (if any)...
1077 * @package Zend_Magic
1079 * @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
1080 * @license http://framework.zend.com/license BSD License
1081 * @version Release: @package_version@
1082 * @link http://framework.zend.com/package/PackageName
1083 * @since Class available since Release 1.5.0
1084 * @deprecated Class deprecated in Release 2.0.0
1086 ]]></programlisting>
1089 The <property>@category</property> annotation must have a value of "Zend".
1093 The <property>@package</property> annotation must be assigned, and should be
1094 equivalent to the component to which the class belongs; typically, this will
1095 only have two segments, the "Zend" prefix, and the component name.
1099 The <property>@subpackage</property> annotation is optional. If provided, it
1100 should be the subcomponent name, minus the class prefix. In the example above,
1101 the assumption is that the class described is either
1102 "<classname>Zend_Magic_Wand</classname>", or uses that classname as part of its
1107 <sect3 id="coding-standards.inline-documentation.functions">
1108 <title>Functions</title>
1111 Every function, including object methods, must have a docblock that contains at
1116 <listitem><para>A description of the function</para></listitem>
1117 <listitem><para>All of the arguments</para></listitem>
1118 <listitem><para>All of the possible return values</para></listitem>
1122 It is not necessary to use the "@access" tag because the access level is already
1123 known from the "public", "private", or "protected" modifier used to declare the
1128 If a function or method may throw an exception, use @throws for all known
1132 <programlisting language="php"><![CDATA[
1133 @throws exceptionclass [description]
1134 ]]></programlisting>
1141 vim:se ts=4 sw=4 et: