Referensi Coding Style

Aturan Penamaan File dan Folder

1. Penamaan Folder Modul

Folder modul ditulis dengan lowercase, jika terdiri dari dua kata atau lebih pisahkan dengan underscore, prefix dapat ditambahkan sesuai kebutuhan.

Contoh: user, login_default, akd_dosen, akd_hasil_studi

  • Aplikasi yang menggunakan database singledb, setiap modulnya wajib menggunakan prefix sesuai aplikasinya masing-masing.
  • Modul yang digunakan oleh gtfw atau yang mengakses tabel berprefik gtfw harus diberi prefix gtfw_. Sedangkan modul yang bersifat umum seperti modul paging tidak menggunakan prefix apapun.
2. Struktur Folder Modul

Folder modul harus memiliki 3 folder di dalamnya, yaitu: business, response, dan template. Nama folder harus berupa lowercase. Tidak ada larangan menambahkan folder lain jika dibutuhkan, meskipun demikian sebaiknya tetap dihindari.

Folder Business

Di dalam folder business dapat ditambahkan folder sesuai kebutuhan tetapi mengikuti engine yang didukung oleh gtfw, seperti: mysqlt, postgres, dll. Folder-folder tersebut untuk menempatkan file-file yang berhubungan dengan akses ke database.

folder business

Gambar 1. Folder Business

Terdapat 2 macam file pada folder mysqlt dan variannya, yang pertama adalah file dengan format nama_file.sql.php, file ini digunakan untuk menyimpan script query, ditulis dengan lowercase dan diakhiri dengan .sql.php. Penamaan file dapat disesuaikan dengan kebutuhan, jika terdiri dari dua kata lebih baik dipisah dengan underscore.

File kedua adalah file dengan format NamaFile.class.php, file ini digunakan untuk menyimpan kelas dan fungsi untuk menjalankan query di file namafile.sql.php. Penamaan file ditulis dengan CamelCase, dan semua kata digabungkan menjadi satu.

folder mysqlt

Gambar 2. Folder mysqlt

Folder Response

Terdapat beberapa jenis file pada folder response, yaitu: View, Do, Print, dan Process. View dan Print adalah file yang berhubungan dengan tampilan di halaman browser, sedangkan Do dan Process berfungsi untuk melaksanakan proses-proses dan tidak berhubungan langsung dengan tampilan. Semua file yang ada di folder response ditulis secara CamelCase dan disesuaikan oleh nama kelasnya.

  • File dengan awalan View dapat memiliki akhiran antara lain:

    • .xls.class.php adalah file untuk menampilkan halaman berupa xls
    • .pdfx.class.php adalah file untuk menampilkan halaman berupa pdf
    • .html.class.php adalah file untuk menampilkan halaman berupa html (baik dengan tipe json maupun html)
    • dan lainnya juga bisa digunakan sesuai kebutuhan devel aplikasi
  • File dengan awalan Do dapat memiliki akhiran antara lain:

    • .html.class.php untuk mengembalikan dengan tipe html
    • .json.class.php untuk mengembalikan dengan tipe json
  • File dengan awalan Process memiliki akhiran .proc.class.php.

    File dengan awalan Process memiliki akhiran .proc.class.php. File ini tidak secara langsung berhubungan dengan core gtfw, melainkan hanya sebagai bantuan untuk meletakkan fungsi-fungsi pemrosesan yang digunakan oleh modul. File dengan awalan Do baik json maupun html akan mengakses file ini. Dengan adanya file proses menjadikan fungsi cukup sekali dibuat dan dapat digunakan bersama-sama oleh file Do dengan tipe json dan html. Untuk penempatan file Process sebaiknya diletakkan di folder business. Karena prosedur ini digunakan sebagai jembatan antara response business yang tidak akan diregistrasikan.

Folder Template

Semua file pada folder template ditulis dengan lowercase dan diakhiri dengan .html. Penamaan nama template mengikuti nama file response yg dipisahkan underscore.

folder template

Gambar 3. Folder Template

3. Struktur Folder Modul Majemuk

Jika terdapat beberapa modul yang saling berkaitan seperti ‘matakuliah setara’, ‘kelompok matakuliah’, ‘jenis matakuliah’, maka namanya dikelompokkan dengan mendahulukan kata yang bersifat umum. Modul tersebut akan bernama ‘prefik_matakuliah_setara’,’prefik_matakuliah_kelompok’,’prefik_matakuliah_jenis’.

Standarisasi Penulisan Kode

1. Indentasi

Gunakan indentasi 3 spasi, tidak menggunakan tab meskipun panjang tab sudah sama dengan 3 spasi.Berikut contoh code dengan indentasi karakter spasi/tab dimunculkan: Contoh indentasi sesuai standar (menggunakan 3 spasi)

function Update() {
---if($updateData = true) {
------$this->SendAlert('Pengubahan data berhasil', 'dosen', $this->CssDone);
---} else {
------$this->SendAlert('Gagal mengubah data', 'dosen', $this->CssFail);
---}
}

Untuk mengotomatiskan indentasi spasi, manfaatkan fitur tab as space pada editor. Biasanya tiap editor berbeda-beda istilah dan cara pengaturannya.

2. Struktur Kontrol

Struktur mencakup juga if, for, while, switch, dan lain-lain. Contoh standar penulisan perintah if

if ((condition1) || (condition2)) {
action1;
} elseif ((condition3) && (condition4))  {
action2;
} else {
defaultaction;
}

Meskipun PHP memperbolehkan tanpa tanda ‘{‘ dan ‘}’ jika actionnya hanya 1 baris, tetapi cara ini harus ditinggalkan, karena kecenderungan developer lupa memberi penutup di bagian akhir setelah else sehingga menyebabkan perbedaan logika. Tidak menyertakan ‘{‘ dan ‘}’ juga memperlambat proses perbaikan bug jika perbaikan tersebut dilakukan dengan menambahkan baris yang mengharuskan menambahkan ‘{‘ dan ‘}’, sebisa mungkin perbaikan bug lebih cepat dilakukan karena biasanya dibutuhkan pada waktu yang sangat terbatas.

Alternatif pengganti if dibolehkan dan dapat ditulis sebagai berikut

$a = $condition1 && $condition2
? $foo : $bar;

$b = $conditional3 && $condition4
? $foo_should_i_wish_do : $bar;

Tidak diperkenankan menuliskan perintah pengganti if hanya dalam 1 baris saja, karena karakter ‘?’ dan ‘:’ akan terpendam di tengah-tengah sehingga sulit terlihat kecuali developer mengamatinya dengan perlahan. Sebisa mungkin semua reserved word dapat terlihat dengan jelas meskipun hanya dilihat sepintas. Namun, jika condition terlalu panjang dapat dipisahkan beberapa baris.

Perintah switch dapat dituliskan sebagai berikut

switch (condition) {
**case 1:**
        action1;
        break;

**case 2:**
        action2;
        break;

**default:**
        defaultaction;
        break;
}

Alignment switch dan case disejajarkan saja, agar tidak terlalu jauh masuk ke kanan karena keberadaan case sudah cukup jelas dilihat meskipun jumlah case ada banyak.

3. Pemberian Komentar
  • Header File

    Wajib menyertakan komentar di bagian header sebagai keterangan dari sebuah class, belum ada standar yang baku terkait komentar header ini, contohnya dapat dilihat berikut

    /**
    * Security Class (singleton)
    * @package Security
    * @author Akhmad Fathonih
    * @copyright Copyright (c) 2014, PT Gamatechno Indonesia
    * @license http://gtfw.gamatechno.com/#license
    */
    
  • Method Khusus

    Pemberian komentar di method khusus yang berhubungan dengan turn over developer.

4. Naming conventions
  • Karakter pada Variabel

    Biasanya variabel dibuat dengan titlecase seperti $dataUserUbah source, meskipun sebagian juga ada yang menggunakan underscore sebagai pemisah kata seperti $data_user_ubah. Masing-masing memiliki kelebihan dan kekurang, penggunaan titlecase lebih ringkas/pendek, tetapi memerlukan perhatian lebih untuk memastikan huruf yang digunakan tepat, bila terjadi kesalahan tidak terdeteksi dengan cepat. Sedangkan penggunan underscore kelemahannya variabel menjadi lebih panjang, tetapi akan sangat mudah dilihat. Selama ini belum ada ketentuan standar penggunaan karakter pada nama variabel.

  • Bahasa pada Variabel

    Tidak ada keharusan penggunaan bahasa pada variabel, mau menggunakan bahasa inggris atau indonesia, umumnya memilih kata yang sederhana yang dapat menggambarkan data yang disimpan pada variabel.

    Warning

    Tidak diperkenankan penggunaan kata yang berlebihan dalam memberi nama variabel, misal $mahasiswa_alien.

  • Class dan Method

    Penamaan kelas disamakan dengan nama file, dan ditulis dengan pola CamelCase. Penamaan method menggunakan kata kerja yang ditulis secara CamelCase. Method tambahan yang bukan perluasan dari base gtfw seperti TemplateModule(), ProcessRequest() dan ParseTemplate(), sebaiknya diletakkan dalam satu source di main/function.

    # Nama File: ViewHelloWorld.html.class.php
    class ViewHelloWorld extend HtmlResponse {
    
    function TemplateModule()
    {
    // template path
    }
    }
    
  • Nama Function dan Array SQL di Folder Business

    Penamaan menggunakan smallCase pada function di class business. Sedangkan untuk penamaan array sql query gunakan lowercase yang dipisahkan underscore, seperti yang tertera pada contoh berikut

    <?php
    ...
    
    function getKelompok() {
            $result = $this->Open($this->mSqlQueries['get_kelompok'], array());
            return $result;
    }
    
    ...
    ?>
    

    Ini berguna untuk mempercepat proses debuging, developer dapat langsung mencari fungsi tersebut ke dalam file sql.

  • Select Field Query dan Pembuatan Alias

    Alias dari select field hanya dibuat ketika terjadi modifikasi pada output field tersebut, jika tidak ada perubahan, biarkan seperti field aslinya, nama hasil select akan selalu digunakan sampai ke file template, berikut contohnya:

    <?php
    ...
    
    $sql['get_kelompoks'] =
    "SELECT
    #tanpa alias
      GroupId,
      GroupName,
    #menggunakan alias
      g.Description AS description,
      g.UnitappId AS group_unit_id,
      gu.UnitName AS unit_kerja
    FROM
      gtfw_group g
    WHERE
    
    ...
    ?>
    
  • Penambahan atau pengubahan css Penambahan atau pengubahan css untuk keperluan aplikasi tertentu dapat dilakukan dengan membuat file css baru dan diletakkan di folder /css/css-custome. Penambahan file css dapat di-load dengan mengedit file sia-mocca-loader.css. Tidak diperkenankan mengubah css selain di 2 tempat yang disebutkan di atas.

  • Pengubahan data oleh aplikasi

    Modul pada aplikasi tidak diperkenankan berisi perintah untuk mengubah data pada tabel yang bukan miliknya. Misal pada aplikasi gtakademik terdapat modul yang mengubah status pembayaran padahal status pembayaran tersebut terdapat pada tabel berprefik ‘finansi _’ yang berarti milik aplikasi gtfinansi. Jika pada suatu kondisi diperlukan proses pengubahan data pada tabel milik aplikasi lain setelah proses pada aplikasi tertentu, maka harus dibuat trigger. Trigger dibuat/dimiliki oleh aplikasi yang punya hak untuk mengubah dan dapat diakses/dijalankan/di-trigger oleh aplikasi lain saat dibutuhkan.