GORAGOD.com

Coding Style Guide PSR-2 ตอนที่ 1

เจตนาของคู่มือนี้เพื่อให้รูปแบบในการเขียนโค้ดเป็นไปในทางเดียวกัน โดยไม่จำเป็นต้องตรงเป๊ะตามมาตรฐานนี้ก็ได้ ทั้งนี้เนื่องจากเครื่องมือแต่ละตัวอาจมีคุณสมบัติบางอย่างไม่สอดคล้องกับมาตรฐานนี้ โดยแนะนำให้ใช้การตกลงกันในทีมและแบ่งปันกฏการจัดรูปแบบนี้ เพื่อให้โค้ดมีรูปแบบเป็นไปในทิศทางเดียวกัน
 

มาตรฐานการเขียนโค้ด

  • การเขียนโค้ดต้องปฏิบัติตาม PSR-1
  • ไฟล์
    • แต่ละบรรทัดของ PHP ต้องปิดด้วย Unix LF เสมอ (ใน Windows จะใช้ \r\n ในการขึ้นบรรทัดใหม่ ในขณะที่บน Unix(หรือ Linux) ใช้ \n อย่างเดียวสำหรับการขึ้นบรรทัดใหม่)
    • จบแต่ละไฟล์ด้วยบรรทัดว่างๆ 1 บรรทัด
    • ไม่ต้องใช้ ?> ปิดที่บรรทัดสุดท้ายของโค้ด หากไฟล์นั้นเป็น PHP ล้วน
  • บรรทัด
    • ใน 1 ไฟล์จะมีกี่บรรทัดก็ได้
    • ในแต่ละบรรทัดสามารถมีจำนวนตัวอักษรสูงสุดไม่เกิน 120 ตัวอักษร (เพื่อให้สามารถเห็นโค้ดทั้งหมดได้โดยไม่ต้องเลื่อนหน้า)
    • ในแต่ละบรรทัดแนะนำให้มีจำนวนตัวอักษรรวมไม่เกิน 80 ตัวอักษร หามีความจำเป็นต้องยาวกว่านั้นแนะนำให้ขึ้นบรรทัดใหม่
    • ที่ท้ายบรรทัดของแต่ละแถวต้องไม่มีช่องว่าง (whitespace) ใดๆ
    • ใน 1 บรรทัดประกอบด้วย 1 คำสั่งเท่านั้น
  • ย่อหน้า
    • ใช้ Space แทน Tab โดยมาตรฐานนี้แนะนำให้ใช้ 1 Tab = 4 Spaces สำหรับแต่ละย่อหน้า (Indent) เนื่องจาก Editor แต่ละตัวอาจมีการกำหนด จำนวน Space ต่อ Tab ไม่เท่ากัน
  • คีย์เวิร์ด และ True, False, Null
    • คีย์เวิร์ดเป็นตัวพิมพ์เล็กเท่านั้น
    • true false และ null ก็ใช้ตัวพิมพ์เล็กเช่นกัน

Namespace และการประกาศตัวแปร

  • เว้น 1 บรรทัดหลังการประกาศ Namespaces
  • การประกาศตัวแปร ให้ทำหลังจากการประกาศ Namespaces แล้ว เท่านั้น
  • สามารถประกาศได้ 1 ตัวแปรต่อ 1 บรรทัดเท่านั้น
  • เว้น 1 บรรทัดหลังการประกาศ use (ในกรณีที่ประกาศ use หลายตัวให้รวมกลุ่มของ use เป็นกลุ่มเดียวกันและเว้น 1 บรรทัดหลังการใช้ use ตัวสุดท้าย)
<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

// ... additional PHP code ...
 

Classes, Properties, และ Methods

กฏนี้ใช้กับ classes, interfaces และ traiits ด้วย
  • Classes
    • extends และ implements จะต้องประกาศในบรรทัดเดียวกันกับการประกาศ Classname
    • การเปิดปิดปีกกา {} ให้ขึ้นบรรทัดใหม่
      <?php
      namespace Vendor\Package;

      use FooClass;
      use BarClass as Bar;
      use OtherVendor\OtherPackage\BazClass;

      class ClassName extends ParentClass implements \ArrayAccess, \Countable
      {
          // constants, properties, methods
       }
       
    • ถ้าจำเป็น รายการ implements แต่ละรายการสามารถขึ้นบรรทัดใหม่ได้ โดยให้ใส่ 1 ย่อหน้า (Indent) ก่อนคำสั่งแต่ละอัน
      <?php
      namespace Vendor\Package;

      use FooClass;
      use BarClass as Bar;
      use OtherVendor\OtherPackage\BazClass;

      class ClassName extends ParentClass implements
          \ArrayAccess,
          \Countable,
          \Serializable
      {
          // constants, properties, methods
       }
       
  • Properties
    • Visibility (ได้แก่ public, private และ protected) ต้องอยู่ก่อน ชื่อ proprerty
    • ไม่ใช้ var เป็น proprerty
    • 1 แถว ต่อ 1 property เท่านั้น
    • ไม่สามารถมี _ (ขีดเส้นใต้) นำหน้าชื่อ property ได้
    <?php
    namespace Vendor\Package;

    class ClassName
    {
        public $foo = null;
    }
     
  • เมธอด
    • Visibility (ได้แก่ public, private และ protected) ต้องอยู่ก่อน ชื่อเมธอด
    • ไม่สามารถมี _ (ขีดเส้นใต้) ในชื่อเมธอดได้
    • การเปิดปิดปีกกา {} ของเมธอด ให้ขึ้นบรรทัดใหม่
    <?php
    namespace Vendor\Package;

    class ClassName
    {
        public function fooBarBaz($arg1, &$arg2, $arg3 = [])
        {
            // method body
         }
    }
     
  • Method Arguments
    • argument แต่ละรายการคั่นด้วยลูกน้ำ (,) และตามด้วยช่องว่าง 1 ช่อง (รายการสุดท้ายไม่ต้องมี)
    • argument ที่เป็น default จะต้องเอาไว้รายการหลังสุดเท่านั้น
    <?php
    namespace Vendor\Package;

    class ClassName
    {
    public function foo($arg1, &$arg2, $arg3 = [])
    {
        // method body
     }
    }
     
    • สามารถแบ่ง argument ออกเป็นหลายๆแถวได้ โดยให้ใส่ 1 ย่อหน้า (Indent) ก่อน argument แต่ละอัน
    • ถ้ามีการแบ่ง argument หลายๆแถว วงเล็บปิด และ ปีกกาเปิด จะอยู่ในบรรทัดถัดไป โดยมีช่องว่างหนึ่งช่องคั่น
    <?php
    namespace Vendor\Package;

    class ClassName
    {
        public function aVeryLongMethodName(
            ClassTypeHint $arg1,
            &$arg2,
            array $arg3 = []
        ) {
            // method body
         }
    }
     
  • abstract, final, and static
    • abstract และ final จะต้องอยู่ก่อน Visibility
    • static จะอยู่ถัดจาก Visibility
    <?php
    namespace Vendor\Package;

    abstract class ClassName
    {
        protected static $foo;

        abstract protected function zim();

        final public static function bar()
        {
            // method body
         }
    }
     
  • การเรียกใช้ เมธอดและฟังก์ชั่น
    • ไม่ต้องมีช่องว่างระหว่างชื่อฟังก์ชั่นและวงเล็บเปิด
    • ไม่ต้องมีช่องว่างถัดจากวงเล็บเปิด และ ก่อนวงเล็บปิด
    • คั่นแต่ละ argument  ด้วยลูกน้ำ (,) ตามด้วยช่องว่าง 1 ช่อง (รายการสุดท้ายไม่ต้องมี)
      <?php
      bar();
      $foo->bar($arg1);
      Foo::bar($arg2, $arg3);
       
    • สามารถแยกรายการ argument ออกเป็นบรรทัดได้เช่นกัน
      <?php
      $foo->bar(
          $longArgument,
          $longerArgument,
          $muchLongerArgument
      );