Komentar dan seksi

Komentar adalah teks yang ditulis untuk pembaca manusia dan diabaikan sepenuhnya oleh penerjemah MATLAB. Topik ini membahas komentar satu baris dengan %, penanda seksi %% untuk mengorganisasi skrip panjang, serta teks bantuan yang menjadikan berkas fungsi terdokumentasi sendiri melalui perintah help. Kebiasaan dokumentasi yang terukur turut dibahas agar komentar tetap padat dan jujur. Hasilnya adalah berkas .m yang tetap dapat dipahami setelah berminggu-minggu tidak disentuh.

Komentar satu baris dengan %#

Semua teks sesudah tanda % sampai akhir baris merupakan komentar dan tidak dieksekusi. Penerjemah melewati bagian itu saat membaca berkas, sehingga komentar tidak menambah beban eksekusi dan jumlahnya bebas disesuaikan dengan kebutuhan. Komentar dapat menempati baris sendiri di atas kode yang dijelaskannya, atau berdiri di belakang pernyataan pada baris yang sama.

% data suhu pagi dalam derajat Celsius
suhu_c = [0 25 100];
% rumus konversi Celsius ke Fahrenheit
suhu_f = 9/5 * suhu_c + 32

suhu_f =

    32    77   212

Kedua komentar pada blok di atas menjelaskan hal yang tidak terbaca dari kodenya sendiri, yaitu satuan data dan rumus yang dipakai. Untuk teks panjang, MATLAB menyediakan komentar blok yang diapit %{ dan %}, dengan syarat masing-masing penanda berdiri sendiri pada barisnya tanpa kode lain. Komentar blok dipakai untuk mencatat asumsi perhitungan atau sumber data di awal skrip tanpa menambah tanda % pada tiap baris.

Seksi dengan %% untuk skrip yang panjang#

Penanda %% memulai seksi sekaligus memberi judul pada sisa barisnya, dan penanda ini dibaca sebagai komentar biasa oleh penerjemah. Perannya yang sesungguhnya ada di editor MATLAB, yang memakai %% untuk membagi berkas menjadi seksi yang dapat dinavigasi, menampilkan kerangka judul, dan menjalankan satu seksi saja melalui Run Section. Laporan catatan suhu pada topik sebelumnya dapat disusun ulang menjadi tiga seksi berikut.

% laporan_seksi.m: ringkasan suhu yang terbagi menjadi tiga seksi

%% Bagian 1: memuat data pengukuran
suhu = [21 23 22 24 25];
% catatan: satuan derajat Celsius, diambil setiap pagi

%% Bagian 2: menghitung ringkasan
banyak = numel(suhu);
rerata = mean(suhu);
terbesar = max(suhu);

%% Bagian 3: melaporkan hasil
fprintf('banyak pengukuran : %d\n', banyak);
fprintf('rerata            : %.1f\n', rerata);
fprintf('terbesar          : %.1f\n', terbesar);

banyak pengukuran : 5
rerata            : 23.0
terbesar          : 25.0

Keluarannya sama dengan versi tanpa seksi karena %% tidak mengubah urutan eksekusi. Perbedaan kedua versi hanya ada pada peran %% di dalam editor. Struktur tiga seksi membuat tiap tahap dapat diuji terpisah, misalnya memeriksa data lebih dahulu sebelum ringkasan dihitung, tanpa menjalankan ulang seluruh berkas. Judul seksi yang menyatakan tugas juga berfungsi sebagai daftar isi yang terbaca sekali pandang.

Teks bantuan pada berkas fungsi#

Blok komentar yang berdiri tepat di bawah baris function menjadi teks bantuan fungsi, dan teks itu ditampilkan oleh perintah help nama. Konvensi penulisannya dimulai dengan ringkasan satu baris yang memuat nama fungsi dengan huruf besar, dilanjutkan dengan baris bentuk pemanggilan beserta penjelasan singkatnya, dan boleh ditutup dengan contoh. Berkas fungsi berikut memakai konvensi tersebut.

function y = konversi_suhu(c)
% KONVERSI_SUHU mengubah suhu Celsius menjadi Fahrenheit.
%   y = KONVERSI_SUHU(c) menghitung 9/5 * c + 32.
%
%   Contoh:
%     konversi_suhu(100)  menghasilkan 212

if nargin < 1
  c = [0 25 100];
end
y = 9/5 * c + 32;
end

Perintah help berikut dijalankan dari folder topik ini sehingga konversi_suhu ditemukan pada folder aktif. Pembaca MATLAB memperoleh keluaran yang setara dengan mengetik help konversi_suhu pada Command Window.

# tampilkan teks bantuan konversi_suhu dari terminal
octave --quiet --eval "help konversi_suhu" 2>/dev/null

'konversi_suhu' is a function from the file /home/kal/my-project/content/matlab/skrip-dan-fungsi/komentar-dan-seksi/konversi_suhu.m

 KONVERSI_SUHU mengubah suhu Celsius menjadi Fahrenheit.
   y = KONVERSI_SUHU(c) menghitung 9/5 * c + 32.

   Contoh:
     konversi_suhu(100)  menghasilkan 212

Additional help for built-in functions and operators is
available in the online version of the manual.  Use the command
'doc <topic>' to search the manual index.

Help and information about Octave is also available on the WWW
at https://www.octave.org and via the [email protected]
mailing list.

Baris-baris sesudah baris lokasi adalah persis isi blok komentar pada berkas, lengkap dengan indentasinya, sehingga dokumentasi dan definisi tidak pernah berpisah. Fungsi itu sendiri bekerja seperti biasa setelah teks bantuannya terbaca.

konversi_suhu([0 25 100])

ans =

    32    77   212

Baris pertama teks bantuan disebut baris H1 dan menjadi sasaran pencarian perintah lookfor, yang memindai baris itu pada seluruh fungsi di path. Karena itu, baris H1 sebaiknya memuat kata kunci yang paling menjelaskan fungsi tersebut, misalnya jenis konversi dan satuannya, agar fungsi tetap ditemukan meskipun namanya terlupa. Sisa baris teks bantuan melayani pembaca yang sudah menemukan fungsinya dan ingin tahu cara memakainya.

Kebiasaan dokumentasi yang terukur#

Komentar yang baik menjelaskan hal yang tidak tampak pada kode, yaitu maksud, satuan, asumsi, dan sumber data, bukan mengulangi apa yang sudah tertulis pada pernyataannya. Jumlahnya proporsional terhadap kejelasan kode, sehingga kode yang sederhana cukup tanpa komentar sama sekali. Perbandingan berikut memperlihatkan bedanya.

Komentar sebaiknya berdiri dekat dengan kode yang dijelaskannya agar keduanya dibaca bersamaan. Saat kode berubah, komentarnya ikut diperbarui pada waktu yang sama, karena komentar basi lebih menyesatkan daripada tidak adanya komentar. Untuk berkas fungsi, teks bantuan menjadi dokumentasi utama karena help selalu menampilkannya kepada siapa pun yang memanggil fungsi tersebut tanpa harus membuka berkasnya.

Tiga lapis dokumentasi pada topik ini bekerja pada jarak yang berbeda. Teks bantuan menjelaskan berkas fungsi secara utuh, judul seksi menjelaskan tahap sebuah skrip, dan komentar satu baris menjelaskan satu pernyataan. Ukuran yang terukur berarti tiap lapis diisi hanya bila pembacanya sungguh membutuhkan penjelasan tambahan, dan lapis yang lebih besar tidak dipakai untuk mengulang isi lapis yang kecil. Dengan pembagian seperti itu, dokumentasi tetap ringkas justru pada program yang panjang.

Kesalahan umum#

• Komentar basi setelah kode diubah. Penjelasan yang tertinggal dari versi lama membuat pembaca berikutnya salah memahami maksud kode. Perbarui komentar pada saat yang sama dengan perubahan kodenya, atau hapus bila tidak relevan lagi.
• Teks bantuan yang terputus. Blok teks bantuan harus mengikuti baris function tanpa baris kosong atau pernyataan kode di antarannya. Bila terputus, help hanya menampilkan bagian yang masih menempel, atau sama sekali tidak menampilkan apa pun.
• Penanda blok %{ yang tidak berdiri sendiri. MATLAB memperlakukan %{ sebagai pembuka blok komentar hanya bila penanda itu sendiri menempati satu baris. Bila ditempel di belakang kode, baris itu menjadi komentar biasa dan baris-baris sesudahnya tetap dieksekusi.

Ringkasan#

• Teks sesudah % sampai akhir baris diabaikan penerjemah sehingga bebas ditulis tanpa memengaruhi eksekusi.
• Penanda %% memberi judul seksi, memungkinkan navigasi dan Run Section di editor, tetapi tetap berupa komentar saat dieksekusi.
• Blok komentar tepat di bawah baris function menjadi teks bantuan yang ditampilkan perintah help nama.
• Komentar yang terukur menjelaskan maksud, satuan, dan asumsi, bukan mengulangi isi kode.

Referensi#

• Add Comments to Code — MathWorks — Panduan resmi penulisan komentar satu baris dan blok %{ %}.
• Add Help for Your Program — MathWorks — Aturan resmi penulisan teks bantuan pada berkas fungsi.
• help — MathWorks — Rujukan perintah help untuk menampilkan teks bantuan.