Setiap Programmer Wajib Tahu Ini!

Ditulis oleh:Waktu baca:

admin~7 menit

Memberi nama adalah pekerjaan yang paling mudah, sekaligus paling sulit.

Mudah karena hanya tinggal ngetik.

Sulit karena nama adalah hal yang sangat-sangat penting. Nama adalah atribut yang akan terus menempel, ibarat “stempel” bagi pemiliknya. Salah sedikit saja bisa berakibat fatal dan berkepanjangan.

Seperti kata pepatah:

There are only two hard things in Computer Science: cache invalidation and naming things.

— Phil Karlton

Di dalam kodingan, nama dari suatu symbol (variable, function, class, dll) akan memberikan persepsi yang kuat di dalam pikiran programmmer. Jika proses penamaan tidak dilakukan dengan baik, akan mengakibatkan project yang dikerjakan sulit untuk di-maintain. Apalagi jika project-nya besar yang dikerjakan oleh banyak programmer.

Contoh penamaan yang kurang baik:

$j = 12;
$stt = 'open' ;

variabel $j maksudnya apa ya?

variabel $stt juga maksudnya apa?

Atau pada REST API misalnya: nama endpoint nya /getUser tapi method nya POST dan isi kodingannya mengupdate data user. 😅 ampun..

Tanpa penamaan yang baik, otak kita akan “dipaksa” bekerja keras untuk menebak maksud dari symbol di dalam sebuah kodingan. Baik kodingan kita sendiri, apalagi kodingan yang ditulis oleh programmer lain.

Jika tidak percaya, silakan buka kodingan sendiri yang kamu buat sebulan yang lalu ! Ada ngga nama variable yang disingkat, terus kamu sulit menebak maksudnya apa? Otak sedikit loading, terus kita baca dulu kode lengkapnya, baru ketahuan… Kalau ada, berarti kamu harus baca postingan ini sampai selesai 😊

Apa saja sih yang perlu diperhatikan dalam memberi nama symbol dalam kodingan kita?

Berikut ini beberapa aturan atau panduan penamaan symbol dalam sebuah kodingan

👇👇

1. Gunakan Nama yang Jelas

Gunakan nama symbol sejelas mungkin!

Usahakan jangan disingkat, karena bisa jadi ambigu.

Seperti pada contoh di atas: variabel $j sebaiknya ditulis secara lengkap, misalnya $jumlah atau $quantity. Karena yang membaca bisa saja menganggap $j itu adalah jarak / jumlah / jam / persepsi lainnya. Sehingga tanpa perlu melihat kodingan secara utuh, sudah bisa diketahui isi dari variabel tersebut adalah jumlah.

Jika hanya ditulis $j saja, mungkin yang membaca harus scroll dulu ke bawah untuk melihat algoritmanya secara lengkap. Kasihan kan? Bagaimana kalau itu adalah kodingan orang lain, dan kita yang harus membaca ? Capek dong… 😫

❌ Don’t:

$j = 12;

✅ Do:

$jarak = 12;

Perjelas Lagi Jika Kurang

Jika nama yang sudah kita set terasa kurang jelas, perjelas lagi !

❌ Don’t:

$jarak = 12; // jika $jarak masih kurang jelas,

✅ Do:

$jarakMeter = 12; // tambahkan $jarakMeter misalnya

❌ Don’t:

$weight = 5;

✅ Do:

$weightKilo = 5;

Sebagai tambahan, jika di suatu block ada dua jenis $jumlah, spesifikkan keduanya! Contoh: $jumlahProduk & $jumlahOrder .

❌ Don’t:

$jumlah      = 21; // jumlah apa maksudnya?
$jumlahOrder = 8;

✅ Do:

$jumlahProduk = 21;
$jumlahOrder  = 8;

Perhatikan Panjang Nama

Nama yang jelas biasanya tidak cukup hanya satu kata, tetapi memerlukan lebih dari satu kata. Yang perlu diperhatikan adalah jangan sampai nama yang diperjelas malah terlalu panjang sehingga sulit dibaca atau diingat.

❌ Don’t:

// nama terlalu panjang
function saveOrderToDatabaseAndSendEmail($order) {

✅ Do:

// sudah cukup jelas
function save($order)

❌ Don’t:

// terlalu spesifik sehingga jadi panjang
$jarakUnsigedBigIntegerDalamMeter = 12;

✅ Do:

// cukup seperti ini
$jarakMeter = 12;

Tidak perlu juga sampai menyebut tipe data nya di dalam penamaan variabel.

Hindari Ambigu

Kembali ke contoh pertama, $stt juga sebaiknya ditulis arti lengkapnya, misalnya $status.

Tanpa ditulis lengkap, bisa jadi ambigu. Contohnya$orderStt ini isinya orderStatus atau orderStatement atau orderStatistics atau apa? Maka sebaiknya dilengkapi menjadi $orderStatus.

❌ Don’t:

$orderStt = 'open';

✅ Do:

$orderStatus = 'open';

Apabila ada nama-nama symbol yang mirip, pertajam lagi perbedaannya, contoh phone, phoneData, phonesInfo : tiga symbol ini cukup membingungkan dan tidak jelas perbedaannya. Perjelas lagi menjadi workPhone, homePhone , allPhones misalnya.

❌ Don’t:

class User {
    function getPhone() {}
    function getPhoneData() {}
    function getPhonesInfo() {}
}
// tidak jelas perbedaannya

✅ Do:

class User {
    function getWorkPhone() {}
    function getHomePhone() {}
    function getAllPhones() {}
}

Rest API

Begitu juga masalah penamaan endpoint /getUser tadi, yang method nya POST, isinya mengupdate data 😞

Sekilas, pembaca akan menganggap isinya adalah mengambil (get) data user. Penamaan tersebut perlu diperbaiki dengan panduan sebagai berikut:

Nama “get” sebaiknya dihilangkan. Karena tidak sesuai dengan isinya yaitu meng-update, bukan mengambil (get).
Dalam panduan standar REST API, method POST seharusnya meng-create resource, bukan meng-update. Untuk meng-update, seharusnya menggunakan method PUT atau PATCH.

❌ Don’t:

+---------+--------+----------------------+
|  name   | method |     what it does     |
+=========+========+======================+
| getUser | POST   | update user resource |
+---------+--------+----------------------+

✅ Do:

+----------------+--------+--------------------------+
|      name      | method |       what it does       |
+================+========+==========================+
| users          | GET    | get user resources       |
| users/{userId} | GET    | get single user resource |
| users          | POST   | create user resource     |
| users/{userId} | PUT    | update user resource     |
| users/{userId} | PATCH  | update user resource     |
| users/{userId} | DELETE | delete user resource     |
+----------------+--------+--------------------------+

Catatan: Dalam REST API, ada panduan standar penamaan endpoint tersendiri yang sepertinya memerlukan postingan tersendiri.

Exception:

Ada pengecualian di mana nama boleh disingkat. Contoh dalam looping yang simple di mana variabel hanya berlaku di scope itu saja.

Boleh:

foreach ($orders as $o) {    
    // $o disingkat di sini masih bisa diterima.
    // karena tidak akan membingungkan
    print($o->status);
}

Atau boleh juga:

foreach ($orders as $order) {
    print($order->status);
}

2. Pastikan Nama Sesuai dengan Isi / Maksud dari Simbol Tersebut

Jika isi suatu variabel adalah email, maka namai $email atau $emailAddress misalnya, jangan namai dengan nama lain yang tidak relevan.

Jika suatu variabel berisi banyak data, contohnya data array, gunakan kata jamak (plural) jangan tunggal (singular).

Contoh: variabel yang berisi daftar order bisa diberi nama$orders (plural) jangan diberi nama$order (singular)

❌ Don’t:

$phone = '[email protected]'; // namanya phone, tapi isinya email
$order = array(); // isinya banyak tapi namanya tunggal

✅ Do:

$email = '[email protected]'; // nama sesuai isi 
$orders = array(); // data banyak menggunakan plural

3. Perhatikan Konteks

Tidak semua penamaan harus selalu detail, jika memang konteksnya sudah mewakili.

Contoh: variabel $orderStatus jika berada di dalam class Order , cukup diberi nama $status. Jadi ketika dipanggil, tinggal dipanggil dengan $order->status sudah cukup jelas, tidak perlu $order->orderStatus yang malah akan menjadi redundancy.

❌ Don’t:

class Order {
    public $orderStatus; // tidak perlu memakai kata "order" lagi

✅ Do:

class Order {
    public $status; // sudah terwakili oleh class "Order"

4. Gunakan Kata Kerja atau Kata Benda pada Konteks Yang Tepat

Penamaan class, sebaiknya berbentuk kata benda. Karena class sendiri secara konsep adalah blueprint dari suatu object (sebuah benda).

Berbeda dengan function. Karena function melakukan pekerjaan tertentu, jadi sebaiknya nama function berbentuk kata kerja.

Contoh penamaan class:

❌ Don’t:

class SendEmail { // send adalah kata kerja 
}

✅ Do:

class Email { // cukup email saja (kata benda)
}

Penamaan Function:

❌ Don’t:

function address() { // bukan kata kerja

Tanpa kata kerja, pembaca akan bingung apa yang dilakukan function tersebut, apakah mengambil atau menyimpan atau apa?

✅ Do:

function getAddress()
// atau
function setAddress($address)
// atau
function deleteAddress($addressId)

5. Ikuti Aturan Standar Yang Berlaku

Setiap bahasa pemrograman biasanya memiliki rekomendasi standar atau style guide masing-masing. Semaksimal mungkin disiplinkanlah diri kita untuk mengikuti standar tersebut !

Standar tersebut ada yang bersifat umum, ataupun khusus bagi internal perusahaan tertentu.

Berikut adalah beberapa contoh standar umum yang bisa kita ikuti:

Dalam satu project, gunakanlah satu standar per bahasa! Jangan mencampur adukan beberapa standar dalam satu project !

Misalnya untuk bahasa php , dalam satu project kita gunakan PSR saja. Jangan mencampur dengan style PEAR / Google misalnya. Tapi jika berbeda project bisa saja menggunakan standar yang lain.

Jika dalam satu project ada beberapa bahasa, bisa menggunakan standar yang lain untuk bahasa yang berbeda. Tetapi tetap gunakan satu standar per bahasa!

Gunakan Fitur/Plugin Autoformat pada IDE

Di dalam IDE, umumnya menyediakan fitur autoformat code dengan mengikuti standar yang tersedia. Sebisa mungkin aktifkan fitur ini, baik dengan shortcut tertentu maupun otomatis ketika save file misalnya.

6. Konsisten Di Semua Tempat

Pertahankan konsistensi penamaan di dalam satu project ! Baik dari segi syntax, istilah, dll.

Contoh: Jika di satu tempat menggunakan istilah fetch untuk konsep mengambil data dari API, gunakan istilah fetch juga di semua tempat dengan konsep nya sama, yaitu mengambil data dari API. Jangan dicampur dengan istilah lain seperti get atau take, kecuali secara konsep memang berbeda.

❌ Don’t:

function fetchUsers() {
// di tempat lain:
function getOrders() { 
// padahal konsepnya sama, mengambil data dari API

✅ Do:

function fetchUsers() {
// di tempat lain:
function fetchOrders() {
// konsep sama, nama seragam

❌ Don’t:

function saveCustomer // menggunakan camelCase
…
function delete_customer // menggunakan snake_case

✅ Do:

// konsisten menggunakan camelCase untuk function name (sesuai standar yang dipilih)
function saveCustomer
…
function deleteCustomer

❌ Don’t:

// menggunakan case style yang berbeda-beda, tidak konsisten
$maxSpeed     = 10;
$initialpower = 50;
$has_nitro    = true;

✅ Do:

// konsisten menggunakan camelCase untuk variable name (sesuai standar yang dipilih)
$maxSpeed     = 10;
$initialPower = 50;
$hasNitro     = true;

7. Hindari Jargon

Hindari kata-kata yang hanya kita atau kalangan tertentu yang tahu ! atau kata-kata gaul yang tidak resmi dan cepat dilupakan, ataupun kata-kata negatif lainnya.

❌ Don’t:

function matiLoe($user)

✅ Do:

function delete($user)

❌ Don’t:

function narsis($avatar)

✅ Do:

function show($avatar)

❌ Don’t:

$dataJadul
$kepo

✅ Do:

$history
$secretCode

8. Perhatikan Urutan Kata

Jika dalam satu blok ada beberapa data sejenis, urutan kata boleh saja dibalik agar terlihat rapi dan konsisten.

❌ Don’t:

function showReport() {
    $userHistory    = $this->user->getHistory();
    $orderHistory   = $this->order->getHistory();
    $paymentHistory = $this->payment->getHistory();
}

✅ Do:

function showReport() {
    $historyUser    = $this->user->getHistory();
    $historyOrder   = $this->order->getHistory();
    $historyPayment = $this->payment->getHistory();
}

Kode yang kedua lebih preferable. Meskipun tidak sesuai grammar, tapi terlihat lebih bagus dan rapi.

Kesimpulan

Sebetulnya masih banyak “aturan” atau “guide” penamaan simbol dalam kodingan ini. Tetapi sepertinya kita cukupkan sekian dulu ya. Soalnya ada yang lebih penting daripada tulisan atau teori, yaitu praktek dan disiplin! 💪

Ayo kita terapkan guide yang ada di tulisan ini dalam kodingan kita, lalu lihat pebedaan kodinganmu dengan yang sebelumnya (yang tidak mengikuti style guide) ! Pasti terlihat lebih cakep atau cantik sekarang ! 😎

Kalau kamu memang sudah biasa mengikuti guide seperti ini, keren 🙌 ! Silakan komentar atau menambahkan item lain yang belum ter-cover di tulisan di atas.

Buat yang lainnya, boleh komentar jika ada yang perlu ditanyakan ataupun yang lainnya…

Akhir kata, mudah-mudahan tulisan ini bisa bermanfaat untuk semua pembaca wabilkhusus untuk penulis sendiri. 😊

Sampai jumpa di postingan lainnya dan Keep Up The Good Code !

Wassalam..

Share postingan ini:

Setiap Programmer Wajib Tahu Ini!

1. Gunakan Nama yang Jelas

Gunakan nama symbol sejelas mungkin!

Perjelas Lagi Jika Kurang

Perhatikan Panjang Nama

Hindari Ambigu

Rest API

Exception:

2. Pastikan Nama Sesuai dengan Isi / Maksud dari Simbol Tersebut

3. Perhatikan Konteks

4. Gunakan Kata Kerja atau Kata Benda pada Konteks Yang Tepat

5. Ikuti Aturan Standar Yang Berlaku

Gunakan Fitur/Plugin Autoformat pada IDE

6. Konsisten Di Semua Tempat

7. Hindari Jargon

8. Perhatikan Urutan Kata

Kesimpulan

Perlu dukungan software, template desain, ataupun ilmu tambahan mengenai digital marketing dan bisnis online ?

WhatsApp Master Closing

WBS Pro

WBS Chat