Laporan Kesenjangan

Topik ini menyusun temuan hambatan porting menjadi laporan kesenjangan yang tertata. Laporan semacam ini mencatat kebutuhan program, status dukungan alat eksekusi, bukti berupa pesan error, dan penyesuaian yang dilakukan, sehingga temuan dapat diperiksa ulang oleh pembaca lain. Kegiatan menyusunnya merupakan bentuk gap analysis, yaitu analisis jarak antara keadaan yang ada dan keadaan yang diharapkan. Di jalur Carbon, laporan ini sekaligus menjadi bahan literasi desain karena setiap kesenjangan menunjukkan batas antara desain tertulis dan alat eksekusi yang ada hari ini.

Fungsi laporan kesenjangan#

Hambatan yang muncul selama porting merupakan data yang mudah menguap. Tanpa pencatatan, kesan yang tersisa hanya berupa pernyataan samar bahwa Carbon belum mendukung satu dan lain hal, dan kesan semacam itu tidak dapat diperiksa, dibandingkan, maupun dibaca ulang ketika alatnya berubah. Laporan kesenjangan mengubah hambatan menjadi butir yang terstruktur, lengkap dengan bukti eksekusi dan waktunya. Bentuk inilah yang membuat laporan tetap berguna setelah dukungan interpreter bertambah, karena status lama dapat disandingkan dengan keadaan terbaru.

Laporan yang baik berbeda dari catatan biasa dalam tiga hal. Pertama, setiap butir memuat pesan error persis sebagaimana muncul, bukan parafrasanya. Kedua, setiap butir dibuktikan oleh program uji terkecil yang dapat dijalankan ulang, bukan oleh potongan program besar yang sukar diurai. Ketiga, statusnya menyebut alat dan waktunya secara eksplisit, misalnya dukungan kompiler Explorer (trunk) pada tanggal eksekusi, karena dukungan sebuah bahasa eksperimental selalu bergerak.

Bagi pembaca jalur ini, laporan kesenjangan juga menjadi materi literasi desain. Satu butir mengajarkan dua hal sekaligus, yaitu bagaimana sebuah kebutuhan program diterjemahkan pada bahasa lain dan di bagian mana desain Carbon berhenti pada tataran tertulis. Kebiasaan membaca laporan semacam ini melatih ketelitian yang sama seperti ketika membaca dokumen desain dan peta jalan proyek.

Kesenjangan yang ditemukan pada proyek ini#

Seluruh temuan pada proyek statistik nilai ujian dikumpulkan dengan pola yang sama. Setiap konstruksi yang tidak dapat ditulis langsung direduksi menjadi program uji terkecil, program itu dieksekusi melalui layanan Compiler Explorer dengan kompiler Explorer (trunk), dan pesan yang muncul disalin apa adanya. Dua program uji terkecil yang mewakili temuan paling struktural diperlihatkan di bawah ini.

package sample api;

fn Main() -> i32 {
  var data: array(i32, 5) = (78, 92, 65, 88, 71);
  Print("nilai pertama: {0}", data[0]);
  return 0;
}

COMPILATION ERROR: <source>:4: could not resolve 'array'

Program pertama mencoba tipe array(i32, 5) yang bentuknya diambil dari dokumen desain, termasuk isi awalnya berupa nilai bertanda kurung. Interpreter menolaknya pada tahap penyelesaian nama, sehingga tidak ada satu elemen pun yang dapat dibaca. Akibatnya, lima nilai ujian pada proyek harus ditulis sebagai variabel skalar terpisah sebagaimana dilakukan pada program terjemahan.

package sample api;

fn Main() -> i32 {
  for (x: i32 in 1..5) {
    Print("{0}", x);
  }
  return 0;
}

SYNTAX ERROR: <source>:4: syntax error, unexpected PERIOD, expecting identifier or BASE or LEFT_PARENTHESIS

Program kedua mencoba perulangan for-in atas rentang 1..5 yang juga mengikuti bentuk desain. Penolakannya terjadi pada tahap penguraian, karena prelude bawaan Explorer belum menyediakan tipe rentang dan kata in memang belum dikenal parsernya. Karena itu, pekerjaan berulang pada proyek ini tetap ditulis dengan while dan pencacah.

Tabel berikut merangkum seluruh temuan proyek ini, termasuk temuan yang bersumber dari program uji pada bagian-bagian sebelumnya dan dari topik-topik lain di jalur ini.

Kolom status pada tabel sengaja menggunakan kata “belum tersedia” dan bukan kata yang menilai bahasanya. Frasa tersebut menunjuk keadaan interpreter pada saat eksekusi dilakukan, sedangkan sebagian bentuk yang dicoba, misalnya array dan for-in, memang sudah ada dalam dokumen desain. Status dan desain dengan demikian tidak dicampur, dan pembaca laporan tetap dapat membedakan keduanya. Pesan pada kolom bukti disalin dari eksekusi nyata, sehingga setiap barisnya dapat diuji ulang dengan program ujinya masing-masing.

Templat laporan dan cara mengisinya#

Templat berikut menampung seluruh unsur yang dibahas pada bagian sebelumnya, mulai dari identitas percobaan, ringkasan porting, tabel kesenjangan, catatan proses, hingga sumber. Templat disimpan sebagai berkas di samping topik ini, sehingga isinya dapat disalin dan diisi untuk proyek porting berikutnya. Baris contoh pada tabelnya diambil langsung dari temuan proyek statistik nilai ujian.

# Laporan kesenjangan porting

Bagian identitas mencatat program C++ asal, alat eksekusi beserta kompiler yang
dipakai, dan tanggal eksekusi. Contoh yang menjadi dasar templat ini adalah
program statistik nilai ujian lima siswa yang dieksekusi ke Carbon Explorer
(trunk) pada compiler-explorer.com.

## Ringkasan porting

Paragraf pertama menyatakan bagian program yang berhasil diterjemahkan dan
dijalankan tanpa perubahan perilaku. Paragraf berikutnya menyatakan bagian yang
harus diubah bentuknya selama porting, misalnya data tetap yang pindah dari
koleksi ke variabel skalar terpisah dan pembaruan objek yang pindah ke pola
nilai kembalian.

## Tabel kesenjangan

| Kebutuhan program | Status di Explorer | Bukti pesan error | Penyesuaian yang dilakukan |
|---|---|---|---|
| Kumpulan data berindeks | belum tersedia | COMPILATION ERROR: could not resolve 'array' | data tetap ditulis sebagai variabel skalar terpisah |
| Perulangan for-in atas rentang | belum tersedia | SYNTAX ERROR: syntax error, unexpected PERIOD | pekerjaan berulang ditulis dengan while dan pencacah |

Baris pada tabel diisi satu kebutuhan per baris, dan pesan error ditulis
persis sebagaimana muncul pada layanan eksekusi agar dapat diperiksa ulang.

## Catatan proses

Catatan proses memuat langkah pencarian kesenjangan yang sudah dilakukan, mulai
dari program uji terkecil yang ditulis, bentuk sintaks desain yang dicoba,
hingga alat yang dipakai untuk mengeksekusi setiap percobaan. Setiap program
uji disimpan sebagai berkas tersendiri agar dapat dijalankan ulang.

## Sumber

Bagian penutup mencantumkan tautan dokumen desain dan layanan eksekusi yang
menjadi dasar setiap status pada tabel kesenjangan.

Pengisian templat mengikuti urutan bagiannya. Bagian identitas mencatat program asal, alat eksekusi beserta kompiler yang dipakai, dan tanggal eksekusi, karena dukungan alat eksperimental selalu bergerak. Tabel kesenjangan diisi satu kebutuhan per baris dengan pesan error yang disalin persis dari layanan eksekusi. Catatan proses merangkum langkah pencarian yang sudah dilakukan, sedangkan bagian sumber memuat tautan dokumen desain dan layanan yang menjadi dasar setiap status.

Satu kebiasaan membuat laporan mudah diperiksa ulang, yaitu menyimpan setiap program uji sebagai berkas tersendiri. Berkas-berkas uji pada topik ini, misalnya uji-array.carbon dan uji-forin.carbon, berada di samping topiknya sehingga dapat dibuka dan dieksekusi ulang kapan saja. Dengan kebiasaan yang sama, laporan porting berikutnya cukup merujuk berkas ujinya tanpa menempel ulang seluruh isinya.

Ringkasan#

• Laporan kesenjangan mengubah hambatan porting menjadi butir yang dapat diperiksa, yaitu kebutuhan program, status dukungan, bukti pesan error, dan penyesuaian yang dilakukan.
• Proyek statistik menghasilkan temuan berupa koleksi, for-in, Print multi-nilai, tipe pecahan, parameter acuan, dan penggabungan String yang belum tersedia di Explorer.
• Kata “belum tersedia” menunjuk keadaan interpreter saat eksekusi dilakukan dan tidak menilai desain bahasanya.
• Setiap temuan disertai program uji terkecil, tanggal eksekusi, dan tautan sumber agar dapat diulang ketika alatnya berubah.

Referensi#

• Compiler Explorer — godbolt.org — Layanan daring tempat seluruh program uji dan pesan error pada topik ini dieksekusi dengan kompiler Explorer (trunk).
• README repositori carbon-lang — Proyek Carbon Language — Menegaskan status eksperimental proyek dan menunjuk alat eksekusi peramban yang dipakai selama pencarian temuan.
• Language design — Carbon Language — Tur desain bahasa yang menjadi sumber bentuk array dan for-in yang dicoba pada program uji.
• Roadmap — Proyek Carbon Language — Peta jalan proyek yang menjelaskan arah pengembangan toolchain sebagai latar perubahan dukungan alat.