1 <appendix id="coding-standard">
2 <title>Zend Framework PHP Coding Standard</title>
3 <sect1 id="coding-standard.overview">
4 <title>Overview</title>
6 <sect2 id="coding-standard.overview.scope">
10 본 문서는 젠드 프래임워크를 개발하는 개발자 개인과 팀 혹은 단체에게 가이드라인과 리소스를 제공하는 문서입니다. 본문서에서는 다음의 주제들이 다루어 집니다.:
13 <para>PHP 파일의 포멧 형식</para>
25 <para>Inline Documentation</para>
31 <sect2 id="coding-standard.overview.goals">
35 바람직한 코딩 규약은 어떤 프로젝트에서나 중요한 요소로 작용합니다. 특히 동일 프로젝트를 여러명의 개발자가 동시에 작업할경우 더더욱 중요합니다. 코딩의 표준 규약은 소스 코드 자체의 높은 품질과, 적은 버그 그리고 손쉬운 유지관리에 많은 도움을 줍니다.
40 <sect1 id="coding-standard.php-file-formatting">
41 <title>PHP 파일의 포멧</title>
43 <sect2 id="coding-standard.php-file-formatting.general">
47 오직 PHP코드만을 포함한 파일에서는, 코드의 맺음 태그("?>")가 절대 허용되지 않습니다. 이는 PHP에 의해서 허용되지 않는 부분입니다. 맺음 태그를 포함하지 않는 것은 공백문자열이 아웃풋된 결과에 삽입되지 않도록 하기 위한 조취입니다.
51 <emphasis>주의:</emphasis> <code>__HALT_COMPILER()</code>에 의해서 생성된 임의적인 바이너리 데이터의 포함은 젠드 프래임워크 php파일 혹은 젠드 프래임워크에 의해 생성된 모든 파일에서 허용되지 않습니다. 이러한 기능의 사용은 특별한 설치 스크립트에 의해서만 허용됩니다.
55 <sect2 id="coding-standard.php-file-formatting.indentation">
58 <para>탭(Tab)이 아닌 4개의 공백문자(space)를 이용해 주십시오.</para>
61 <sect2 id="coding-standard.php-file-formatting.max-line-length">
62 <title>최대 허용 라인 줄수</title>
65 한줄에 허용되는 글자수는 80글자를 기준으로 삼습니다. 개발자는 가능한한 한줄안에 80컬럼내의 문자가 삽입되도록 해주십시요. 그러나 그 이상의 글자도 가능은 합니다. PHP 코드의 최대 허용 글자수는 120 캐릭터입니다.
69 <sect2 id="coding-standard.php-file-formatting.line-termination">
70 <title>라인 터미네이션(줄바꾸기)</title>
73 라인 터미네이션(줄바꾸기)은 유닉스 텍스트 파일의 그것과 동일합니다. 라인은 라인피드(LF)로 항상 끝나야 합니다. 라인피드(Linefeeds)는 오디날(ordinal) 10 혹은 16진수로 0x0A로 표현합니다.
77 메킨토시 컴퓨터에서 쓰이는 캐리지 리턴(CR,0x0D)은 이용하지 마십시오.
81 윈도우 컴퓨터에서 쓰이는 return/linefeed 조합(CRLF,0x0D, 0x0A)은 이용하지 마십시오.
86 <sect1 id="coding-standard.naming-conventions">
89 <sect2 id="coding-standard.naming-conventions.classes">
93 젠드 프래임워크는 클라스 이름과 그 클래스가 존재하는 디렉토리의 위치가 상호 매칭되는 구조를 가지고 있습니다.젠드 프래임워크의 최상위 디렉토리는 "Zend/"디렉토리이며 모든 클라스들은 이 아래에 계층적으로 위치하게 됩니다.
97 클라스 이름은 오직 알파벳만 포함할수 있습니다. 클라스 이름에 숫자가 허용은 되지만 권장되지는 않습니다. 밑줄(_)은 경로 구분자를 대체하는 역활로만 쓰입니다. -- 파일이름 "Zend/Db/Table.php"는 클라스 이름 "Zend_Db_Table"와 매칭이 되어야 합니다.
101 만약 클라스 이름이 하나 이상의 단어로 이루어진경우, 각 단어의 첫번째 단어는 대문가 되어야 합니다. 하지만 클라스이름에서 연이은 대문자의 조합은 허용되지 않습니다. 예를 들면 "Zend_PDF"는 허용되지 않는 형태이고 "Zend_Pdf"는 허용되는 형태입니다.
105 프레임워크와 함꼐 배포되어지는 젠드사 혹은 젠드사의 파트너 회사들의 클라스들은 항상 "Zend_" 라는 문구로 시작되며 "Zend/" 디렉토리 아래에 계층적으로 위치하게 됩니다.
112 <programlisting role="php"><![CDATA[
120 <emphasis>주의:</emphasis>프레임워크와 연동은 되지만 프레임워크의 일부가 아닌 코드들은 (젠드나 젠트 파트너사 가 아닌 일반 사용자에 의해 제작된 코드) "Zend_"라는 이름으로 시작해서는 절대 안됩니다.
124 <sect2 id="coding-standard.naming-conventions.interfaces">
128 인터페이스 클라스들은 다른 클라스들과 마찬가지의 이름 규칙을 이용합니다. 단 인터페이스들은 그 클라스 이름의 마지막이 "Interface"로 끝나야 합니다. 예:
130 <programlisting role="php"><![CDATA[
131 Zend_Log_Adapter_Interface
132 Zend_Controller_Dispatcher_Interface]]>
137 <sect2 id="coding-standard.naming-conventions.filenames">
141 그 외에 모든 파일들은 알파벳과 밑줄(_) 그리고 대쉬(-)만이 그 이름에 허용됩니다. 공백문자는 허용되지 않습니다.
145 어떠한 파일이던 PHP 코드를 포함하고 있는 파일들은 ".php"의 확장자를 가져야 합니다. 다음의 예제들은 윗 섹션에서 예를 들었던 클라스들이 포함된 허용가능한 파일이름들입니다:
148 <programlisting role="php"><![CDATA[
151 Zend/Controller/Front.php
153 Zend/View/Helper/FormRadio.php]]>
155 파일이름들은 반드시 위에 기술된 대로 클라스 이름에 매핑되어야 합니다.
159 <sect2 id="coding-standard.naming-conventions.functions-and-methods">
160 <title>함수(Function)와 메소드들</title>
163 Function의 이름들은 알파벳만이 허용됩니다. 밑줄(_)은 허용되지 않습니다. Function이름에 숫자는 허용이 되나 권장되는 사항은 아닙니다.
167 Function 이름들은 항상 소문자로 시작하여야 합니다. Function 이름이 하나의 문자 이상으로 이루어져 있을경우 새로 덧붙여지는 새 단어의 첫글자는 대문자야여 합니다. 이는 일반적으로 "camelCaps" 방식이라고 불리어 집니다.
171 Function 이름을 그 기능을 짐작할수 있게 만드는것은 권장됩니다. 그 기능을 짐작할수 있게 지어진 Function의 이름은 코드를 이해하는데 실질적으로 많은 도움이 됩니다.
175 다음은 권장되는 Function 이름들의 예입니다:
178 <programlisting role="php"><![CDATA[
188 객체 지형 언어에서 객제에 대한 접근자들은 항상 "get"이나 "set"이라는 접두어를 가지고 있습니다. Singleton 이나 Factory pattern등의 디자인 패턴을 이용하는 경우, 메소드 이름들은 해당 패턴들을 좀더 쉽게 인식할수있는 패턴 이름을 포함하고 있어야 합니다.
192 전역(global scope, floating functions) 함수는 허용이 되지만 권장되지 않습니다. 하나 Function은 하나의 스타틱 클라스안에서만 이루어지기를 권장합니다.
196 <sect2 id="coding-standard.naming-conventions.variables">
200 변수명은 오직 알파멧만 허용이 됩니다. 밑줄(_)은 허용되지 않습니다. 변수명에 숫자는 허용이 되지만 권장되지는 않습니다.
204 "private"나 "protected"로 선언된 클라스 멤버 변수들은 그 이름의 첫 시작이 하나의 밑줄(_)로 시작되어야 합니다. 이는 Function 이름에서 밑줄이 허용되는 유일한 경우입니다. "Publice"으로 정의된 맴버 변수들은 밑줄(_)로 시작되어서는 안됩니다.
208 Function 이름과 같이 (섹션 3.3을 참고) 변수의 이름들은 소문자로 시작되면 "camelCaps"의 대소문자 규정을 따릅니다.
212 그 특성을 나타내는 설명구의 이름은 권장됩니다. 변수들은 가능한한 그 역활을 나타내는 쪽으로 이름지어져야 합니다. "$i" 나 "$n"과 같은 단순한 변수명은 단순한 반복문에서를 제외하고는 권장되지 않습니다. 만약 반복구문이 20줄 이상의 크기라면 변수의 이름은 좀더 그 역활이 기술되어있는 쪽으로 지어져야 합니다.
216 <sect2 id="coding-standard.naming-conventions.constants">
220 상수의 이름들은 알바벳 캐릭터와 밑줄(_)을 동시에 포함할수 있습니다. 상수의 이름에 숫자는 허용됩니다.
224 상수의 이름은 반드시 대문자로 이루어져야 합니다.
228 시각적으로 좀더 쉬운 해독을 위하여, 상수의 단어들은 밑줄(_)로 나뉘어 져야 합니다. 예를 들어 <code>EMBED_SUPPRESS_EMBED_EXCEPTION</code>은 허용되어 지나 <code>EMBED_SUPPRESSEMBEDEXCEPTION</code>은 허용되지 않습니다.
232 상수는 반드시 "const" 지시어를 써서 클라스 맴버로 정의되어야 합니다. 전역변수로서 "define" 지시어와 함께 정의된 상수는 가능은 하나 권장되지 않습니다.
237 <sect1 id="coding-standard.coding-style">
238 <title>코딩 스타일</title>
240 <sect2 id="coding-standard.coding-style.php-code-demarcation">
241 <title>PHP 코드의 구분</title>
244 PHP 코드는 항상 완젹한 표준 PHP 테그의 형태로 구분지어져야 합니다:
246 <programlisting role="php"><![CDATA[<?php
248 ?>]]></programlisting>
252 테그의 단축형은 허용되지 않습니다. 오직 PHP 코드만을 포함하고 있는 파일의 경우, 맺음 테그는 반드시 생략하여야 합니다.(See <xref linkend="coding-standard.php-file-formatting.general" />).
256 <sect2 id="coding-standard.coding-style.strings">
259 <sect3 id="coding-standard.coding-style.strings.literals">
260 <title>단순 문자열</title>
263 어떠한 변수도 포함하지 않은 단순 문자열의 경우 단따옴표 혹은 어퍼스트로피를 이용하여 문자열을 구별지어야 합니다:
265 <programlisting role="php"><![CDATA[
266 $a = 'Example String';]]>
271 <sect3 id="coding-standard.coding-style.strings.literals-containing-apostrophes">
272 <title>단따옴표를 포함한 문자열</title>
275 문자열 자체가 어퍼스트로피(단따옴표)를 포함하고 있는 경우, "상따옴표"를 이용하여 구별되어 질수 있습니다. 이는 특히 SQL 구문의 처리시 유용합니다:
277 <programlisting role="php"><![CDATA[
278 $sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";]]>
281 The above syntax is preferred over escaping apostrophes.
285 <sect3 id="coding-standard.coding-style.strings.variable-substitution">
286 <title>변수의 치환</title>
289 변수의 치환은 다음 두가지 방법으로 허용됩니다.:
291 <programlisting role="php"><![CDATA[
292 $greeting = "Hello $name, welcome back!";
294 $greeting = "Hello {$name}, welcome back!";]]>
299 동일성을 위하여 다음의 형태는 허용되지 않습니다:
301 <programlisting role="php"><![CDATA[
302 $greeting = "Hello ${name}, welcome back!";]]>
307 <sect3 id="coding-standard.coding-style.strings.string-concatenation">
308 <title>변수의 연결</title>
311 문자변수들은 "." 연산자를 이용하여 상호 연결됩니다. 좀더 편안한 가독을 위해 반드시 공백문자열이 "." 연산자 전후에 위치해야 합니다:
313 <programlisting role="php"><![CDATA[
314 $company = 'Zend' . 'Technologies';]]>
319 "." 연산자를 이용하여 문자열을 합칠때,
320 When concatenating strings with the "." operator, it is permitted to
321 break the statement into multiple lines to improve readability. In these
322 cases, each successive line should be padded with whitespace such that the
323 "."; operator is aligned under the "=" operator:
325 <programlisting role="php"><![CDATA[
326 $sql = "SELECT `id`, `name` FROM `people` "
327 . "WHERE `name` = 'Susan' "
328 . "ORDER BY `name` ASC ";]]>
334 <sect2 id="coding-standard.coding-style.arrays">
337 <sect3 id="coding-standard.coding-style.arrays.numerically-indexed">
338 <title>산술 인덱스 어레이</title>
340 <para>음수는 인텍스로서 허용되지 않습니다.</para>
343 An indexed array may be started with any non-negative number, however
344 this is discouraged and it is recommended that all arrays have a base index of 0.
348 When declaring indexed arrays with the <code>array</code> construct, a trailing space must be
349 added after each comma delimiter to improve readability:
351 <programlisting role="php"><![CDATA[
352 $sampleArray = array(1, 2, 3, 'Zend', 'Studio');]]>
357 It is also permitted to declare multiline indexed arrays using the "array" construct.
358 In this case, each successive line must be padded with spaces such that beginning of
359 each line aligns as shown below:
361 <programlisting role="php"><![CDATA[
362 $sampleArray = array(1, 2, 3, 'Zend', 'Studio',
369 <sect3 id="coding-standard.coding-style.arrays.associative">
370 <title>Associative Arrays</title>
373 When declaring associative arrays with the <code>array</code> construct, it is encouraged
374 to break the statement into multiple lines. In this case, each successive line must be
375 padded with whitespace such that both the keys and the values are aligned:
377 <programlisting role="php"><![CDATA[
378 $sampleArray = array('firstKey' => 'firstValue',
379 'secondKey' => 'secondValue');]]>
385 <sect2 id="coding-standard.coding-style.classes">
386 <title>Classes</title>
388 <sect3 id="coding-standard.coding-style.classes.declaration">
389 <title>Class Declaration</title>
392 Classes must be named by following the naming conventions.
394 The brace is always written on the line underneath the class name ("one true brace" form).
396 Every class must have a documentation block that conforms to the PHPDocumentor standard.
398 Any code within a class must be indented four spaces.
400 Only one class is permitted per PHP file.
402 Placing additional code in a class file is permitted but discouraged. In these files, two blank lines must separate the class from any additional PHP code in the file.
404 This is an example of an acceptable class declaration:
406 <programlisting role="php"><![CDATA[
408 * Documentation Block Here
412 // entire content of class
413 // must be indented four spaces
419 <sect3 id="coding-standard.coding-style.classes.member-variables">
420 <title>클라스 뱀버 변수</title>
423 Member variables must be named by following the variable naming conventions.
425 Any variables declared in a class must be listed at the top of the class, prior
426 to declaring any functions.
428 The <code>var</code> construct is not permitted. Member variables always declare
429 their visibility by using one of the <code>private</code>, <code>protected</code>,
430 or <code>public</code> constructs. Accessing member variables directly by making
431 them public is permitted but discouraged in favor of accessor
437 <sect2 id="coding-standard.coding-style.functions-and-methods">
438 <title>Functions and Methods</title>
440 <sect3 id="coding-standard.coding-style.functions-and-methods.declaration">
441 <title>Function and Method Declaration</title>
444 Functions must be named by following the naming conventions.
446 Functions inside classes must always declare their visibility by using
447 one of the <code>private</code>, <code>protected</code>,
448 or <code>public</code> constructs.
450 Like classes, the brace is always written on the line underneath the
451 function name ("one true brace" form).
453 There is no space between the
454 function name and the opening parenthesis for the arguments.
456 Functions in the global scope are strongly discouraged.
458 This is an example of an acceptable function declaration in a class:
460 <programlisting role="php"><![CDATA[
462 * Documentation Block Here
467 * Documentation Block Here
469 public function bar()
471 // entire content of function
472 // must be indented four spaces
479 <emphasis>NOTE:</emphasis> Passing by-reference is permitted in the function declaration only:
481 <programlisting role="php"><![CDATA[
483 * Documentation Block Here
488 * Documentation Block Here
490 public function bar(&$baz)
497 Call-time pass by-reference 는 금지되어 있습니다.
502 반환되는 값은 괄호로 처리되여서는 안됩니다. 괄호안에 쌓인 반환값은 젠드 프레임워크의 가독력을 방해하며 반환되는 리퍼런스로 메소드가 변환될시 코드에 피해를 줄수도 있습니다.
504 <programlisting role="php"><![CDATA[
506 * Documentation Block Here
513 public function bar()
521 public function bar()
531 <sect3 id="coding-standard.coding-style.functions-and-methods.usage">
532 <title>Function과 Method의 사용</title>
535 Function의 인자(arguments)들은 콤파 구분자와 하나의 공백문자로 구분되어 집니다. 다음은 세개의 인자를 가지고 있는 Function의 허용예입니다:
537 <programlisting role="php"><![CDATA[
538 threeArguments(1, 2, 3);]]>
543 Call-time pass by-reference is prohibited. See the function declarations section
544 for the proper way to pass function arguments by-reference.
546 For functions whose arguments permitted arrays, the function call may include the
547 "array" construct and can be split into multiple lines to improve readability. In
548 these cases, the standards for writing arrays still apply:
550 <programlisting role="php"><![CDATA[
551 threeArguments(array(1, 2, 3), 2, 3);
553 threeArguments(array(1, 2, 3, 'Zend', 'Studio',
555 56.44, $d, 500), 2, 3);]]>
561 <sect2 id="coding-standard.coding-style.control-statements">
562 <title>Control Statements</title>
564 <sect3 id="coding-standard.coding-style.control-statements.if-else-elseif">
565 <title>If / Else / Elseif</title>
568 Control statements based on the <code>if</code> and <code>elseif</code>
569 constructs must have a single space before the opening parenthesis of the conditional,
570 and a single space after the closing parenthesis.
574 Within the conditional statements between the parentheses, operators must be separated
575 by spaces for readability. Inner parentheses are encouraged to improve logical grouping
576 of larger conditionals.
580 The opening brace is written on the same line as the conditional statement. The closing
581 brace is always written on its own line. Any content within the braces must be
582 indented four spaces.
584 <programlisting role="php"><![CDATA[
592 For "if" statements that include "elseif" or "else", the formatting must be
593 as in these examples:
595 <programlisting role="php"><![CDATA[
611 PHP allows for these statements to be written without braces in some circumstances.
612 The coding standard makes no differentiation and all "if", "elseif" or "else" statements
617 Use of the "elseif" construct is permitted but highly discouraged in favor of the
618 "else if" combination.
622 <sect3 id="coding-standards.coding-style.control-statements.switch">
623 <title>Switch</title>
626 Control statements written with the "switch" construct must have a single space before
627 the opening parenthesis of the conditional statement, and also a single space after
628 the closing parenthesis.
632 All content within the "switch" statement must be indented four spaces. Content under
633 each "case" statement must be indented an additional four spaces.
636 <programlisting role="php"><![CDATA[
637 switch ($numPeople) {
650 The construct <code>default</code> may never be omitted from a <code>switch</code> statement.
654 <emphasis>NOTE:</emphasis> It is sometimes useful to write a <code>case</code> statement which falls through
655 to the next case by not including a <code>break</code> or <code>return</code> in that case. To distinguish
656 these cases from bugs, any <code>case</code> statement where <code>break</code> or <code>return</code> are
657 omitted must contain the comment "// break intentionally omitted".
662 <sect2 id="coding-standards.inline-documentation">
663 <title>Inline Documentation</title>
665 <sect3 id="coding-standards.inline-documentation.documentation-format">
666 <title>Documentation Format</title>
669 All documentation blocks ("docblocks") must be compatible with the phpDocumentor format.
670 Describing the phpDocumentor format is beyond the scope of this document.
671 For more information, visit: <ulink url="http://phpdoc.org/">http://phpdoc.org/</ulink>
675 All source code file written for Zend Framework or that operates with the framework
676 must contain a "file-level" docblock at the top of each file and a "class-level" docblock
677 immediately above each class. Below are examples of such docblocks.
681 <sect3 id="coding-standards.inline-documentation.files">
685 Every file that contains PHP code must have a header block at the top of the file that
686 contains these phpDocumentor tags at a minimum:
688 <programlisting role="php"><![CDATA[
690 * Short description for file
692 * Long description for file (if any)...
694 * LICENSE: Some license information
696 * @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
697 * @license http://www.zend.com/license/3_0.txt PHP License 3.0
699 * @link http://dev.zend.com/package/PackageName
700 * @since File available since Release 1.2.0
706 <sect3 id="coding-standards.inline-documentation.classes">
707 <title>Classes</title>
710 Every class must have a docblock that contains these phpDocumentor tags at a minimum:
712 <programlisting role="php"><![CDATA[
714 * Short description for class
716 * Long description for class (if any)...
718 * @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
719 * @license http://www.zend.com/license/3_0.txt PHP License 3.0
720 * @version Release: @package_version@
721 * @link http://dev.zend.com/package/PackageName
722 * @since Class available since Release 1.2.0
723 * @deprecated Class deprecated in Release 2.0.0
729 <sect3 id="coding-standards.inline-documentation.functions">
730 <title>Functions</title>
733 Every function, including object methods, must have a docblock that contains at a minimum:
736 <listitem><para>A description of the function</para></listitem>
737 <listitem><para>All of the arguments</para></listitem>
738 <listitem><para>All of the possible return values</para></listitem>
743 It is not necessary to use the "@access" tag because the access level is already known
744 from the "public", "private", or "protected" construct used to declare the function.
748 Function이나 Method의 익셉션 throw 할경우, @thorws를 이용해야 합니다:
750 <programlisting role="php"><![CDATA[
751 @throws exceptionclass [description]]]>