Standar Penulisan Coding PSR-1

Tulisan ini adalah catatan lama tentang Standar Penulisan Coding ketika mengikuti sesi diskusi kuliah telegram PHPID for students tentang PHP OOP (sekitar tanggal 13 Desember 2016 lalu). Dalam sesi diskusi tersebut, ada satu pertanyaan yang masih saya ingat sampai sekarang dan tepatnya teringat kembali ketika mempelajari framework Laravel belakangan ini. Ada peserta diskusi yang menyebutkan tentang standarisasi dalam penulisan coding PHP. Kala itu standar penulisan coding ini memang belum sempat saya coba implementasikan, meski saya memang sudah pernah memikirkannya. Setelah saya googling, ternyata banyak web dan blog yang merujuk ke PSR-1. Jadi, apa sih PSR-1 itu?

1. PSR-1: Basic Coding Standard

PSR (PHP Standars Recommendation)-1 adalah rekomendasi PSR untuk standarisasi dalam coding PHP. Di dalamnya terdapat hal-hal yang perlu kita perhatikan dalam penulisan coding. Adanya standarisasi coding ini sangat bermanfaat untuk kita sebagai developer. Misalkan kalau semua pengembang menggunakan standar coding yang sama itu akan sangat mudah untuk memindahkan modul tanpa adanya masalah.

Berdasarkan PSR-1, ada beberapa hal yang mesti kita perhatikan dalam penulisan coding, Apa saja itu? Check this out ya!

2. File

Di dalam file PHP, terdapat tiga poin yang menjadi standar berdasar PSR-1, di antaranya:

2.1. PHP Tags

Seperti yang kita ketahui, ada beberapa variasasi tag yang sering kita jumpai saat coding PHP. Nah, berdasarkan rekomendasi PSR-1, ada tag yang HARUS digunakan dalam code PHP. Ya, dalam code PHP HARUS menggunakan tag <?php ?> atau menggunakan tag <?= ?>. Dan dalam penggunaan tag disarankan tidak menggunakan variasi tag yang lainnya.

2.2. Character Encoding

Selain PHP tags, kita juga harus memperhatikan Character Encoding lho! Nah, Code PHP HARUS menggunakan Character Encoding UTF-8 tanpa BOM.

2.3. Side Effects

Biasanya, di dalam sebuah file itu ada pendeklarasian simbol baru dan ada file yang berisi logika yang dapat menyebabkan side-effect. Berdasarkan rekomendasi dalam PSR-1, dalam file itu SEBAIKNYA TIDAK melakukan pendeklarasian simbol baru dan menuliskan logika yang menyebabkan side-effect secara bersamaan dalam satu file yang sama. Jadi kalau kita membuat file SEBAIKNYA deklarasi simbol baru (class, function, constant, dll), code yang tidak menyebabkan side-effect lainnya dipisah dengan code PHP yang mengeksekusi logic dengan side-effect.

Jadi apa yang dimaksud dengan side effect di dalam codingan ini? Prasa side-effect itu maksudnya adalah eksekusi logika yang tidak terkait langsung dengan deklarasi Class, Function, Constants dll, biasanya hal ini terdapat saat melampirkan file lain (include). Sebagai contoh ada beberapa hal yang termasuk diantaranya adalah :

Generating output,
Penggunaan require atau include,
Menghubungkan ke external service,
Memodifikasi ini setting,
Menampilkan pesan error atau exception,
Memodifikasi global atau variable static,
Membaca atau menulis file
dan lain sebagainya.

Berikut ini adalah contoh file dengan penggunaan deklarasi dan side effect secara bersamaan, yang notabene adalah yang HARUS dihindari:

 <?php
 // side effect: change ini settings
 ini_set('error_reporting', E_ALL);

 // side effect: loads a file
 include "file.php";

 // side effect: generates output
 echo "<html>\n";

 // declaration
 function foo()
 {
   // function body
 }

Lalu seperti apa contoh yang disarankan dalam PSR-1? Di bawah ini adalah contoh file yang berisi deklarasi tanpa efek samping yang disarankan dalam PSR-1.

 <?php
 // declaration
 function foo()
 {
   // function body
 }

 // conditional declaration is *not* a side effect
 if (! function_exists('bar')) {
   function bar()
   {
     // function body
   }
 }

3. Namespace dan nama Class

Dalam penulisan Namespace dan nama Class juga ada standar penulisannya lho! Pertama, Namespace dan Class HARUS mengikuti PSR "autoloading" [PSR-0, PSR-4]. Ini artinya dalam satu file itu hanya ada satu class dan di dalamnya terdapat namespace setidaknya satu level: tingkat atasnya ada nama vendor.

Kedua, Nama Class HARUS dideklarasikan dalam penulisan StudlyCaps. Selain itu, code yang ditulis untuk PHP 5.3 dan setelahnya HARUS menggunakan namespace. Nah, kamu bisa perhatikan di code di bawah:

 <?php
 // PHP 5.3 and later:
 namespace Vendor\Model;

 class Foo
 {

 }

Bisa kita lihat pada baris kode di atas, terdapat namespace sebelum deklarasi class.

Lalu, bagaimana kalau kode masih ditulis dengan PHP 5.2.x ke bawah? Kode yang ditulis untuk PHP 5.2.x dan sebelumnya disarankan menggunakan pseudo-namespacing convention atau prefix Vendor_ pada nama class.

Contoh penulisannya bisa kita lihat seperti code di bawah:

 <?php
 // PHP 5.2.x and earlier:
 class Vendor_Model_Foo
 {

 }

4. Class Constants, Properties dan Methods

Berdasar PSR-1, ada beberapa hal yang perlu diperhatikan dalam penulisan Constant, properties dan methods dalam sebuah Class. Oh iya, Istilah class di sini mengacu pada semua class, interface dan trait. Dan di bawah ini adalah Basic Coding Standard di dalam Class:

4.1. Constant

Constant milik sebuah class HARUS dideklarasikan dalam penulisan huruf kapital semuanya dengan pemisah underscore. Sebagai contoh:

 <?php
 namespace Vendor\Model;

 class Foo
 {
   const VERSION = '1.0';
   const DATE_APPROVED = '2012-06-01';
 }

Bisa kita lihat di contoh di atas, penulisan constant menggunakan huruf kapital semuanya (VERSION) dan menggunakan pemisah underscore "_" apabila nama constant yang kita pakai itu menggunakan dua kata (DATE_APPROVED).

4.2. Properties

PSR-1 menghindari rekomendasi dalam hal penggunaan $StudlyCaps, $camelCase atau $under_score dalam penamaan Properties. Itu artinya kita bisa menggunakan gaya penulisan yang mana saja. Mau StudlyCaps, $camelCase atau under_score, itu diperbolehkan

Hanya saja ada satu hal yang mesti kita ingat. Apapun Penamaan properties yang digunakan, SEBAIKNYA diimplementasikan secara konsisten sesuai scope. Scope tersebut boleh jadi pada vendor-level, package-level, class-level, atau method-level.

4.3. Methods

Berdasarkan PSR-1, nama Method itu HARUS dideklarasikan dalam penulisan camelCase().

Code Formatting Tools

Untuk membiasakan diri menggunakan gaya penulisan coding yang disarankan itu memang perlu usaha yang luar biasa. Kabar baiknya ada tools yang memudahkan kita untuk melakukan format secara otomatis disesuaikan dengan PSR. Berikut ini tools yang bisa kita gunakan untuk melakukan format file project kita.

***

Begitulah, ternyata ada beberapa hal yang mesti kita perhatikan dalam penulisan coding. Dengan adanya standar Penulisan Coding tentu akan memudahkan developer. Terutama saat code PHP kita share ke depelover lainnya. Hal ini tentu akan memudahkan depelover dalam memahami code PHP tersebut. Tidak hanya untuk developer lain, tapi untuk kita sendiri sebagai developer code tersebut tentunya. Hal ini bisa dirasakan saat kita membuka kembali code yang sudah lama tersimpan di repositori yang sudah lama tidak kita buka.

Yuk kita perbaiki gaya penulisan coding kita.

***

Referensi: PSR-1 @ http://www.php-fig.org/psr/psr-1/

Untuk mempelajari lebih jauh, boleh baca juga tentang: PSR-12: Extended Coding Style

Dan list keseluruhannya bisa diakses di sini: PHP Standards Recommendations

php