CakePHP Coding Standard

Cake Developers จะใช้มาตรฐานการโค้ดดังต่อไปนี้

#การเพิ่มคุณสมบัติใหม่
ไม่ควรเพิ่มคุณสมบัติใหม่ โดยไม่ได้ทดสอบระบบซึ่งควรจะทำก่อนน้ำเข้าไปบันทึกยัง repository

#การจัดย่อหน้า
1 tab จะถูกใช้เพื่อจัดย่อหน้า

#โครงสร้างควบคุม
<?php
if ((expr_1) || (expr_2 )) {
    // action_1;
} elseif (!(expr_3) && (expr_4)) {
    // action_2;
} else {
    // default_action;
}
?>
- ในโครงสร้างควบคุมควรจะมี 1 ช่องว่างก่อนที่จะถึงวงเล็บเปิด และ 1 ช่องว่างระหว่างวงเล็บสุดท้ายกับ bracket {
- ใช้ brackets เสมอแม้ว่ามันไม่จำเป็น ซึ่งจะอ่านโค้ดได้ง่ายขึ้น
- การเปิด bracket ควรจะอยู่ในบรรทัดเดียวกับโครงสร้างควบคุม.
การปิด bracket ควรจะวางอยู่บนบรรทัดใหม่, และมันควรจะมีระดับย่อหน้าระดับเดียวกับ
โครงสร้างควบคุม. คำสั่งใน bracket ควรจะเริ่มในบรรทัดใหม่และโค้ดข้างในควรจะจัดย่อหน้าอยู่ในระดับสูงขึ้น
<?php
// wrong - no brackets, badly placed statement
if (expr) statement;

// wrong - no brackets
if (expr)
    statement;

// good
if (expr) {
    statement;
}
?>


# ternary operator
อย่าใช้ ternary operator (?). เราต้องการให้ cake code base อ่านได้ง่ายเท่าที่เป็นไปได้
และเราเชื่อว่าการใช้ full if-else จะทำให้มันดูดีกว่า, อ่านง่ายกว่าและสำคัญที่สุดคือ debug ได้ง่ายกว่า

# การเรียก Function
Function ควรจะถูกเรียกโดยไม่มีช่องว่างระหว่างชื่อ function และวงเล็บเปิด,
และมันควรจะมีช่องว่างระหว่างแต่ละ parameter ในการเรียกใช้ function

<?php
$var = foo($bar, $bar2, $bar3);
?>
อย่างที่คุณเห็นข้างบนควรจะมีช่องว่างหน้าและหลังเครื่องหมายเท่ากับ

#การประกาศ method
<?php
function someFunction($arg1, $arg2 = '') {
    if (expr) {
        statement;
    }
    return $var;
}
?>
parameter ที่มีค่า default, ควรจะวางอยู่ที่ตำแหน่งสุดท้ายใน parameter.
พยายามทำให้ function คืนค่าบางอย่าง อย่างน้อย true หรือ false - เพื่อสามารถระบุได้ว่า
function ทำงานสำเร็จหรือไม่

#การให้คำอธิบายโค้ด
comment ทั้งหมดควรจะเขียนโดยใช้ภาษาอังกฤษ, และวิธีที่จะอธิบายบล๊อกที่ถูกอธิบายได้ชัดเจน

comment สามารถมี phpDocumentor tags ดังต่อไปนี้
    * @access
    * @author
    * @copyright
    * @deprecated
    * @example
    * @ignore
    * @internal
    * @link
    * @see
    * @since
    * @tutorial
    * @version
    * inline {@internal}}
    * inline {@inheritdoc}}
    * inline {@link}}

PhpDoc tagas คล้ายกับ JavaDoc tags มาก. Tag จะถูกประมวลผลถ้ามันอยู่เป็นสิ่งแรกใน
บรรทัดของ DocBlock, ตัวอย่างเช่น:
<?php
 /**
 * Tag example.
 * @author this tag is parsed, but this @version is ignored
 * @version 1.0 this tag is also parsed
 */
?>

มีเพียงแค่ 3 inline tags ({@internal}, {@inheritdoc} และ {@link})
<?php
/**
 * Example of inline phpDoc tags.
 *
 * This function works hard with {@link foo()} to rule the world.
 */
function bar() {
}
 
/**
 * Foo function
 */
function foo() {
}
?>

# การ include file
เมื่อ include file class หรือ libraies, จะต้องใช้ require_once เท่านั้น

# PHP tags
ใช้ <?php ?> ไม่ใช้ <? ?>

# Functions
ตั้งชื่อทุกๆ function ในแบบ camelBack
<?php
function longFunctionName() {
}
?>

# Classes
ชื่อคลาสควรจะใช้ CamelCase, ตัวอย่างเช่น
<?php
class ExampleClass {
}
?>

# Variables
ชื่อตัวแปรควรจะอธิบายให้ชัดเจนเท่าที่เป็นไปได้, แต่ควรจะสั้นเท่าที่เป็นไปได้.
โดยปกติตัวแปรควรจะเริ่มต้นด้วย lowercase, และควรจะเขียนในแบบ camelBack
ในกรณีที่มีหลายคำ. สำหรับตัวแปรที่เป็น object ควรเริ่มต้นด้วยตัวอักษรตัวใหญ่
<?php
$user = 'John';
$users = array('John', 'Hans', 'Arne');

$Dispatcher = new Dispatcher();
?>

# Member visibility
เนื่องจากเราไม่สามารถใช้ PHP5 private และ protected keyword สำหรับ methods หรือ variables
เราเห็นด้วยกับการใช้กฎต่อไปนี้:
- protected method หรือ variable จะเริ่มต้นด้วย _
- private method หรือ variable จะพเริ่มต้นด้วย __

# Example addresses
สำหรับ url, mail address จะใช้ข้อมูลดังต่อไปนี้
example:
    * Email: someone@example.com
    * WWW: http://www.example.com
    * FTP: ftp://ftp.example.com
โดเมนเนม example.com ถูกจองเพื่อใช้เป็นตัวอย่าง (ดูที่ RFC 2606) และแนะนำว่าให้ใช้ใน
เอกสาร หรือใช้เป็นตัวอย่าง

# Files
ไฟล์ควรจะเขียนใน lower case และถ้าไฟล์มีหลายคำควรจะแบ่งด้วย underscore

# Variable types
ประเภทตัวแปรที่ใช้ใน DocBlocks:
mixed ตัวแปรที่สามารถมีได้หลายชนิด
integer ตัวเลขจำนวนเต็มทุกชนิด
float ตัวเลขจำนวนจริง
boolean ค่าตรรกกะ (true หรือ false)
string สตริง (ค่าใดๆ ใน "" หรือ '')
array อะเรย์
object ออบเจค
resource รีซอร์ซ ตัวอย่างเช่นค่าที่ return จาก mysql_connect()

# Constants
ค่าคงที่ควรจะกำหนดเป็นตัวใหญ่
<?php
define('CONSTANT', 1);
?>

ถ้าในค่าคงที่มีหลายคำควรจะแบ่งคำด้วย underscore
<?php
define('LONG_NAMED_CONSTANT', 2);
?>

Ref: http://book.cakephp.org/view/509/Coding-Standards