Pemilihan Proyek

Proyek penutup jalur ini berupa pustaka utilitas durasi kecil bernama pustaka-waktu, yaitu pustaka untuk konversi satuan durasi dan pemformatannya tanpa satu pun dependensi. Topik ini membahas kriteria pemilihan proyek, keputusan antara membangun pustaka atau aplikasi beserta konsekuensinya, penentuan cakupan versi 0.1, dan pembuatan folder awal pustaka tersebut. Setiap fungsi pada versi 0.1 dianotasi penuh lalu dibuktikan berjalan melalui program uji yang dieksekusi dengan node. Setelah langkah-langkahnya diikuti, pustaka kecil dengan pemanggil nyata sudah siap menghadapi pemeriksaan tipe yang lebih ketat.

Tiga kriteria pemilihan#

Tiga kriteria menyaring ide proyek penutup, yaitu konsumen nyata, cakupan kecil, dan nilai tipe yang tinggi. Ketiganya menilai ide dari sisi yang paling menentukan hasil pengerjaan, bukan dari sisi keragaman fiturnya. Proyek yang lolos ketiga saringan melatih secara penuh keterampilan yang diselesaikan jalur ini.

Konsumen nyata berarti ada pihak lain yang memanggil kode, baik berupa modul lain, berkas uji, maupun pengembang lain. Konsumen inilah yang menguji apakah tanda tangan fungsi beserta tipenya sudah nyaman dipakai, karena setiap ketidaknyamanan langsung terlihat pada pemanggilannya. Proyek tanpa konsumen nyata mudah berakhir sebagai kode yang ditulis sekali dan tidak pernah dipanggil lagi, sehingga disiplin API-nya tidak pernah diuji.

Cakupan kecil membuat proyek selesai dalam beberapa sesi kerja, sehingga seluruh siklus pengerjaan sempat dilalui. Siklus yang dimaksud mencakup menulis fungsi, memberi tipe, menjalankan program uji, sampai memasang gerbang pemeriksaan otomatis. Proyek yang terlalu luas biasanya berhenti di tengah jalan, dan bagian pemeriksaan otomatis menjadi korban pertama karena terasa seperti pekerjaan tambahan.

Nilai tipe tinggi berupa ranah data yang bentuk nilainya terstruktur dan salah hitungnya mahal. Durasi, jadwal, dan konversi satuan memenuhi syarat itu, karena kekeliruan satuan merupakan error yang sering terjadi dan tipe mampu menangkapnya sebelum program berjalan. Pustaka durasi kecil dengan demikian memenuhi ketiga kriteria sekaligus.

Pustaka atau aplikasi#

Keputusan berikutnya memilih bentuk proyek, yaitu pustaka atau aplikasi, karena keduanya menuntut jenis kedisiplinan yang berbeda. Pustaka adalah kode yang dipakai kode lain, sedangkan aplikasi adalah kode yang dipakai orang. Perbedaan yang terdengar sederhana itu menjalar ke hampir setiap keputusan pengerjaan.

Pada pustaka, produk utamanya berupa permukaan API, yaitu himpunan fungsi dan tipe yang diekspor. Konsumennya adalah pengembang lain yang mengimpor pustaka, sehingga setiap perubahan tanda tangan fungsi publik langsung merusak kode pemanggilnya. Pada aplikasi, produk utamanya berupa pengalaman pengguna, sedangkan tipe melindungi model data internal dan alur data di balik layar. Konsekuensinya, pustaka melatih disiplin menjaga kontrak, sedangkan aplikasi melatih disiplin menjaga perilaku yang terlihat oleh pengguna.

Tabel berikut merangkum perbedaan kedua bentuk tersebut.

Proyek penutup ini dipilih berbentuk pustaka karena konsumen nyatanya paling mudah dibuktikan. Sebuah berkas uji dapat dituliskan sebagai pemanggil pertama, dan keluarannya dapat diperiksa langsung di terminal. Bukti semacam itu penting karena seluruh topik pada modul ini menggarap pustaka yang sama dari tahap pemilihan sampai gerbang CI.

Menentukan cakupan versi 0.1#

Cakupan versi 0.1 ditetapkan lebih dahulu agar pekerjaan punya garis selesai yang jelas. Versi 0.1 merupakan versi awal yang belum menjanjikan kestabilan, dan semver, yaitu skema penomoran mayor.minor.patch, menetapkan nomor mayor 0 sebagai masa pengembangan awal ketika bentuk API masih boleh berubah. Dengan garis itu, fungsi yang tidak masuk versi 0.1 ditunda tanpa mengganggu, dan cakupan kecil tetap terjaga.

Cakupan pustaka-waktu versi 0.1 terdiri atas dua kelompok kemampuan, yaitu konversi satuan durasi dan pemformatan durasi. Konversi bergerak antara menit dan jam, sedangkan pemformatan mengubah jumlah menit menjadi teks yang enak dibaca. Daftar berikut menjadi kontrak awal versi 0.1.

• menitKeJam(menit: number): number mengubah menit menjadi jam dalam bilangan desimal.
• jamKeMenit(jam: number): number mengubah jam menjadi menit.
• uraikanMenit(menit: number): { jam: number; menitSisa: number } memecah menit menjadi pasangan jam dan sisa menit.
• formatDurasi(menit: number): string menyusun teks durasi seperti “1 jam 30 menit”.
• formatJamDesimal(menit: number): string menyusun teks durasi dalam jam desimal seperti “1.5 jam”.

Di luar cakupan versi 0.1 ada zona waktu, penguraian teks tanggal, dan penyesuaian bahasa. Ketiganya berisiko melebarkan pustaka durasi kecil menjadi pustaka tanggal-jam penuh, sehingga seluruhnya ditunda sampai versi 0.1 terbukti stabil. Garis cakupan seperti ini juga memudahkan menilai kapan versi 0.1 dinyatakan selesai.

Folder awal pustaka-waktu#

Folder pustaka-waktu memuat folder src untuk kode sumbernya dan satu berkas uji pada akar folder proyek. Dua modul pertama dipisah menurut perannya, yaitu src/konversi.ts untuk konversi satuan dan src/format.ts untuk pemformatan teks. Pemisahan tersebut membuat setiap berkas punya satu alasan untuk berubah.

Isi src/konversi.ts berupa tiga fungsi konversi dengan anotasi penuh pada parameter dan nilai kembaliannya.

export function menitKeJam(menit: number): number {
  return menit / 60;
}

export function jamKeMenit(jam: number): number {
  return jam * 60;
}

export function uraikanMenit(menit: number): { jam: number; menitSisa: number } {
  const jam = Math.floor(menit / 60);
  const menitSisa = menit % 60;
  return { jam, menitSisa };
}

Isi src/format.ts berupa dua fungsi pemformatan yang menerima jumlah menit lalu menyusun teksnya.

export function formatDurasi(menit: number): string {
  const jam = Math.floor(menit / 60);
  const sisa = menit % 60;
  if (jam === 0) {
    return `${sisa} menit`;
  }
  if (sisa === 0) {
    return `${jam} jam`;
  }
  return `${jam} jam ${sisa} menit`;
}

export function formatJamDesimal(menit: number): string {
  const jam = menit / 60;
  return `${jam.toFixed(1)} jam`;
}

Kedua modul tidak mengimpor apa pun, sehingga masing-masing dapat dibaca sendiri. Anotasi menutup seluruh parameter dan nilai kembalian, sehingga pemanggil selalu tahu bentuk masukan dan keluarannya. Tidak ada satu pun tipe yang dibiarkan menggantung pada kedua berkas ini.

Berkas uji menjadi konsumen pertama pustaka. Berkas ini mengimpor kedua modul, memanggil kelima fungsi versi 0.1, dan mencetak hasilnya di terminal. Karena mengimpor berkas lokal, eksekusinya ditunjukkan melalui perintah node pada blok di bawahnya.

// tidak-dijalankan
import { formatDurasi, formatJamDesimal } from "./src/format.ts";
import { jamKeMenit, menitKeJam, uraikanMenit } from "./src/konversi.ts";

console.log(formatDurasi(90));
console.log(formatDurasi(45));
console.log(formatDurasi(120));
console.log(formatJamDesimal(90));
console.log(menitKeJam(90));
console.log(jamKeMenit(1.5));
console.log(uraikanMenit(135));

# menjalankan program uji pustaka langsung dengan node
node --no-warnings pustaka-waktu/uji.ts

1 jam 30 menit
45 menit
2 jam
1.5 jam
1.5
90
{ jam: 2, menitSisa: 15 }

Keluaran tersebut memperlihatkan konsumen nyata yang bekerja. formatDurasi(90) menghasilkan teks “1 jam 30 menit”, formatJamDesimal(90) menghasilkan “1.5 jam”, dan uraikanMenit(135) menghasilkan pasangan { jam: 2, menitSisa: 15 }. Program uji ini kelak berperan sebagai pengaman, karena setiap perubahan pustaka wajib membuatnya mencetak keluaran yang sama.

Kesalahan umum#

• Memilih proyek hanya karena teknologinya menarik tanpa menelusuri siapa konsumennya. Proyek semacam itu jarang sampai pada tahap API yang dipakai orang lain, sehingga keterampilan menjaga kontrak tidak terlatih. Tanpa konsumen yang jelas, daftar fungsinya pun tersusun dari tebakan. Perbaikannya berupa memulai dari daftar tiga kriteria dan menuliskan siapa pemanggilnya sebelum kode pertama ditulis.
• Menetapkan cakupan versi 0.1 yang mencakup zona waktu dan penguraian tanggal sekaligus. Cakupan semacam ini membuat pustaka belum selesai ketika waktu pengerjaan habis, dan kekurangan waktu biasanya baru disadari di tahap akhir. Perbaikannya berupa menuliskan daftar fungsi versi 0.1 dan menunda sisanya sampai versi tersebut stabil.
• Menulis fungsi pustaka tanpa anotasi dengan rencana mengetik belakangan. Anotasi yang menyusul biasanya tidak pernah tuntas, dan pemanggil pertama langsung mewarisi tipe yang kabur. Tipe yang kabur pada fungsi pertama cenderung tersalin ke fungsi-fungsi berikutnya. Perbaikannya berupa menganotasi tanda tangan fungsi pada baris pertama saat fungsi itu dibuat.

Ringkasan#

• Proyek penutup dipilih dengan tiga kriteria, yaitu konsumen nyata, cakupan kecil, dan nilai tipe yang tinggi.
• Pustaka menghadirkan konsumen berupa pemanggil API, sedangkan aplikasi menghadirkan konsumen berupa pengguna akhir, dan keduanya menuntut kedisiplinan yang berbeda.
• Versi 0.1 pustaka-waktu terbatas pada konversi menit-jam dan pemformatan durasi dalam lima fungsi beranotasi penuh.
• Program uji berperan sebagai konsumen pertama yang membuktikan pustaka berjalan dengan keluaran nyata.

Referensi#

• Everyday Types — TypeScript Handbook — Panduan anotasi tipe pada variabel, fungsi, dan tipe objek yang dipakai pada tanda tangan fungsi versi 0.1.
• Semantic Versioning 2.0.0 — semver.org — Spesifikasi penomoran mayor.minor.patch yang menetapkan mayor 0 sebagai masa pengembangan awal.