Yudi Maryanto Blog

Pada umumnya sebuah framework terdiri dari ratusan kalau tidak ribuan entity dan tentu saja jauh lebih banyak lagi jumlah member dan parameter yang terdapat di dalamnya. Developer yang menggunakan framework tersebut membutuhkan panduan yang menyeluruh serta harus ada sesuatu yang bisa selalu mengingatkan mereka tentang tujuan serta cara penggunaannya. Dokumentasi API reference tidaklah menyelesaikan masalah. Jika developer harus selalu merujuk ke dokumentasi untuk sekedar menjawab pertanyaan yang sangat sederhana, maka hal itu akan sangat memakan waktu dan mengurangi produktivitas developer.

Pada skenario yang paling sederhana, sebuah framework harus bisa dipakai tanpa perlu membaca dokumentasi. Banyak developer yang lebih senang menulis kode program dengan cara coba-coba (trial and error) dan baru membaca dokumentasi ketika cara penggunaan framework tersebut tidak sesuai dengan intuisi mereka.

Berikut ini adalah panduan untuk prisip Self-Documenting API:

Lakukan:
Pastikan bahwa API yang kita buat cukup intuitif sehinga pada skenario yang paling sederhana, API kita bisa digunakan tanpa perlu melihat dokumentasi.

Lakukan:
Buatlah dokumentasi yang lengkap untuk semua API yang kita buat.

Dokumentasi yang lengkap memegang perangan yang sangat penting. Hal ini karena tidak mungkin bagi kita untuk membuat API yang benar-benar self-documenting. Developer akan merasakan level yang berbeda-beda tentang seberapa jauh API kita bersifat self-documenting. Hal ini tergantung akan skill serta pengalaman masing-masing developer. Selain itu, dokumentasi juga sangat penting bagi tipe developer yang mana ia lebih senang mempelajari dan memahami dahulu arsitektur keseluruhan framework baru mulai menulis kode program.

Lakukan:
Jadikan diskusi tentang pemilihan nama entity menjadi bagian utama dari proses desain framework kita.

Hati-hatilah dalam memilih nama entitiy. Lakukan analisis dan diskusikan dengan sungguh-sungguh tentang nama yang secara umum diketahui orang ketika dihadapkan pada sebuah skenario. Misalnya kita sedang membahas tentang file I/O. Dalam hal ini, jika kita menamakan kelas utama kita dengan nama File, hal itu akan sangat intuitif jika dibandingkan dengan NtfsFile, FatFile, dll. Hal ini karena ketika berurusan dengan file I/O, seorang developer akan cenderung mencari kelas dengan nama File. Akan sangat bijak jika kita buat kelas File sebagai kelas utama dan sekaligus menempatkan method-method yang terlibat dalam skenario utama di dalam kelas File ini.

Selain itu, jika kita menggunakan sistem hierarki (NtfsFile merupakan kelas utama dan merupakan turunan kelas File) maka developer yang akan menggunakan framework ini harus mengetahui terlebih dahulu tentang struktur hierarki dari kelas-kelas yang terlibat yang pada akhirnya akan semakin memperumit object model dari framework yang kita buat.

Jangan:
Takut untuk memilih nama yang cukup jelas bagi sebuah entity.

Seorang developer akan jauh lebih sering membaca nama sebuah entity daripada mengetikkannya. Apalagi dengan kehadiran tools-tools canggih semacam intellisense, maka intesitas mengetik nama sebuah entity akan semakin jauh berkurang. Oleh karena itu, penamaan entity yang jelas akan sangat membantu seorang developer dalam memahami sebuah kode program. Sebagai contoh, nama method KatalogLaporan.CetakLaporanTahunan adalah jauh lebih baik daripada misalnya KtlgLprn.CetakLprnThn.

Lakukan:
Libatkan ahli tata bahasa dalam pemilihan nama entity sejak awal proses pembuatan sebuah framework. Saran dan masukan dari mereka merupakan sesuatu yang akan sangat membantu karena mereka lebih mengetahui kata-kata yang tepat yang akan mudah dipahami oleh developer pengguna framework kita.

Pertimbangkan:
untuk mencadangkan nama-nama terbaik untuk sebuah entity. Jangan menghamburkan nama-nama intuitif untuk skenario selain skenario utama. Jika kita punya nama intuitif untuk sebuah entity, namun entity tersebut baru akan ditambahkan ke framework pada versi yang akan datang, maka simpan dahulu nama tersebut. Jangan gunakan di framework yang sekarang.

Lakukan:
Gunakan pesan exception untuk mengkomunikasikan kepada developer tentang penggunaan framework yang salah. Sebagai contoh:

 

EventLog log = new EventLog();

//log.Source = “Mailing Service”;

log.WriteEntry(“Mail Arrived”);

 

 

 

Kode di atas jika dijalankan akan menimbulkan exception dengan pesan Source property was not set before writing to the event log. Hal ini akan cukup jelas mengkomunikasikan kepada developer bahwa dia telah salah menggunakan kelas EventLog karena lupa belum mengeset property Source.

Lakukan:
Sebisa mungkin, usahakan untuk membuat API kita bersifat strongly typed.

string name = Customer.Name;

string name = Customer.Properties["Name"].ToString();

 

Baris pertama program di atas tentu lebih intuitif daripada baris kedua. Selain itu, pada contoh di atas, dengan membuat API kita bersifat strongly typed, maka kita bisa membuat property Name langsung mengembalikan tipe data string sementara jika menggunakan property bag seperti pada baris kedua, maka data yang dikembalikan bertipe object dan kita harus melakukan konversi lagi. Selain itu, keuntungan lain menggunakan strongly typed API adalah kita mendapat dukungan penuh dari intellisense yang otomatis akan mengurangi tingkat kesalahan tulis kita.

Lakukan:
Pastikan bahwa API kita konsisten dengan .NET Framework atau framework yang lain yang sering digunakan oleh developer yang akan menggunakan framework kita. Konsistensi merupakan salah satu kata kuncil dalam self-documenting API. Jika API kita konsisten dengan framework yang developer sudah akrab dengannya, maka ketika memprogram menggunakan framwork kita, developer akan merasa bahwa framwork kita alami dan intuitif.

Hindari:
terlalu banyak abstraksi pada API yang ada di skenario utama. Terlalu banyak abstraksi akan menyebabkan developer harus memahami keseluruhan arsitektur dar framework kita bahkan untuk skenario yang paling sederhana.