Dokumentasi Program

Setiap program yang dibuat, seharusnya memiliki dokumentasi.

Mengapa?

Karena program yang telah selesai dibuat belum tentu dapat langsung sempurna, sesuai dengan yang diperlukan oleh penggunanya. Perlu ada :

  • pengembangan untuk dapat memenuhi keperluan penggunanya.
  • Terkadang program harus ada perbaikan, jika ternyata pada saat digunakan ditemukan kesalahan.

Dokumentasi juga berguna untuk menginformasikan tentang proses yang ada dalam program, sehingga jika ada pertanyaan tentang program yang dibuat memiliki kemampuan apa saja, kita dapat mengetahui atau menjelaskan berdasarkan dokumentasi.

Dokumentasi program sangat diperlukan oleh pemilik aplikasi, jika ingin mengembangkan aplikasinya bukan oleh pengembang yang sama. Pengembang lain yang diserahi tugas untuk mengembangkan aplikasi dapat dengan cepat mempelajari dari dokumentasi tersebut.

Macam dokumentasi program

Macam dokumentasi program:

  • dokumentasi spesifikasi program
  • dokumentasi teknis program
  • dokumentasi penggunaan program 

Dokumentasi spesifikasi program

Dokumentasi spesifikasi program seharusnya sudah ada sebelum program dibuat. Dibuat oleh perancang aplikasi (sering kali dibuat oleh analis sistem). Berdasarkan dokumentasi inilah program dibuat.

Dokumentasi spesifikasi program ini dibuat untuk memberikan panduan tentang logika program yang harus dibuat. Harus ada proses apa saja, bagaimana flow prosesnya. Pemrogram dapat melakukan coding dengan lebih mudah.

Akan tetapi, sering terjadi, dokumentasi spesifikasi program tidak dibuatkan oleh perancang aplikasinya. Perancang aplikasi hanya menjelaskan tentang program, spesifikasi program yang ada adalah spesifikasi secara lisan. Akibatnya adalah seringkali program tidak sesuai dengan yang diinginkan, karena pemrogram bekerja dengan mengandalkan ingatannya, bukan berdasarkan panduan dokumen spesifikasi. (Bahasa guyonnya adalah dokumentasi by lisan).

Ketiadaan dokumentasi bisa menyebabkan komunikasi antara perancang aplikasi dan pemrogram menjadi tidak baik, karena bisa jadi akan ada perselisihan akibat ketidakjelasan akan apa yang dikerjakannya.

Dokumentasi spesifikasi program harus ada, walaupun secara global. Setidaknya ada informasi tentang poin-poin yang harus ada dalam program, kemudian bagaimana urutan prosesnya.

Dokumentasi spesifikasi program menjadi pegangan bersama antara perancang, pemrogram, dan penguji. Untuk memastikan bahwa program yang dibuat sudah sesuai dokumentasi.

Dokumentasi Kode Program

Dokumentasi kode program, merupakan dokumentasi yang harus ada dalam program, untuk memberikan penjelasan kepada setiap baris atau pun blok perintah dalam program.

Dokumentasi program diperlukan bagi programmer itu sendiri, untuk dapat menelusuri logika program. Karena biasanya, pemrogram akan lupa akan alur programnya sendiri. Apalagi jika sudah lama sudah ditinggalkan, karena mengerjakan pekerjaan lain. Pada saat harus memperbaiki atau menyempurnakan, programmer sering harus mempelajari terlebih dahulu alur programnya sendiri, baru kemudian baru bisa melakukan modifikasi sesuai dengan yang diinginkan.

Dari sisi lain, dokumentasi juga diperlukan untuk memudahkan untuk memvalidasi apakah program yang telah dikembangkan, sudah sesuai dengan yang dispesifikasikan atau belum. Proses validasi ini akan dilakukan oleh tim penguji (validator).

Dokumentasi kode program merupakan pelengkap dokumentasi spesifikasi, karena menjelaskan bagaimana dari spesifikasi diterjemahkan ke dalam program.

Jika dokumentasi spesifikasi tidak ada maka dokumentasi kode program akan menjadi dokumentasi yang sangat berharga, karena bukan menjadi dokumen pelengkap tetapi menjadi dokumentasi utama.

Dokumentasi dalam kode program umumnya dilakukan dengan menuliskan baris-baris komentar dalam kode sumber programnya. Isi dari dokumentasi kode program, setidaknya terdiri atas:

  • langkah-langkah dalam program untuk menyelesaikan masalah
  • komentar dituliskan pada setiap awal modul atau fungsi,
  • jika mungkin komentar ditulis pada setiap blok program, jika tidak maka ditulis pada blok-blok yang penting saja. Lebih baik lagi jika setiap baris ada komentarnya.
  • Informasi tentang siapa yang membuat, kapan pertamakali dibuat, kapan terakhir diperbaiki, jika mungkin informasi perubahan dari waktu ke waktu

Cara menuliskan komentar harus mengikut kepada cara penulisan yang baku. Jika menggunakan bahasa pemrograman Java, maka dapat menggunakan format yang telah ditetapkan oleh javadoc.

Dokumentasi Penggunaan Program

Dokumentasi penggunaan program sangat diperlukan untuk dapat memberitahu kepada pengguna bagaimana cara menggunakan program yang telah dibuat. Jika tidak dibuatkan cara menggunakan programnya, dikhawatirkan program menjadi tidak dapat dipakai, apalagi jika programnya kurang interaktif.

Banyak program yang dibuat, cara pemakaiannya sesuai dengan alur logika pemrogramnya. Bukan berdasarkan alur logika pengguna program. Karenanya harus dibuatkan dokumentasi cara menggunakan program, agar pengguna tahu bagaimana cara menggunakan dengan benar.

Tools

Jika kita hanya memiliki dokumentasi kode program, maka kita dapat mengambil dokumentasi dari kode program tersebut untuk menjadi seolah-olah dokumentasi spesifikasi program. Kita harus menggunakan tools untuk melakukan pengambilan dokumentasi kode program dengan menggunakan tools.

Agar dokumentasi dalam kode program dapat diambil oleh tools yang akan digunakan, maka cara penulisan dokumentasi harus mengikuti standar tertentu. Jika kita menggunakan Java, maka kita dapat menggunakan javadoc untuk mengambil dokumentasinya. Untuk bahasa pemrograman lain ada juga toolsnya. Masing-masing memiliki tools yang membantu untuk membuatkan dokumentasi dari dokumentasi kode program.

Beberapa tools yang umum digunakan adalah:

  • javadoc
  • delphidoc
  • doxygen

doxygen (http://www.doxygen.org/) adalah tools open source yang paling umum digunakan, yang digunakan untuk membuat dokumentasi dari source program.

Advertisements

Memilih Editor Teks Untuk Penyuntingan Program

Banyak editor teks yang dapat digunakan untuk membantu pembuatan program, dari program yang paling sederhana sampai dengan yang sangat kompleks (baca: lengkap).

Untuk yang sederhana kita kenal adalah program edit di lingkungan DOS, notepad di lingkungan Windows, atau vi di lingkungan *nix.

Untuk yang kompleks, kita akan memiliki editor yang bisa digunakan untuk membuat banyak program dengan satu editor saja, umumnya menggunakan konsep plugin. Contoh editor ini adalah eclipse. Ada juga editor yang kompleks kemampuannya, tetapi hanya untuk digunakan mengembangkan program dengan bahasa pemrograman tertentu saja, seperti editor Delphi. Editor yang spesifik ini umumnya terintegrasi dengan lingkungan pengembangan pemrograman bahasa tersebut, dikenal dengan IDE (Integrated Deveploment Editor).

Pada beberapa kasus, kita ingin juga memiliki editor yang kompleks, tidak terikat dengan bahasa pemrograman tertentu, tetapi ringan. Ringan di sini adalah program tidak terlalu besar dan cepat dalam penggunaanya (tidak lambat dalam proses penyuntingan).

Beberapa kriteria untuk memilih editor yang ringan dan lengkap, adalah sebagai berikut:

  • Syntax highlighting
    Adalah kemampuan dari editor untuk menandai isi dari program, mana yang merupakan bagian dari perintah program, dan mana yang bukan (misal data)
  • Kunci-kunci penyuntingan standar
    Editor harus memiliki standar kunci penyuntingan, seperti misalnya di Windows, semua kunci-kunci penyuntingan standar sama dengan yang ada di Windows, seperti misalnya Ctrl-C untuk menyalin ke dalam memori, Ctrl-V untuk mengeluarkan dari memori ke editor, Ctrl-S untuk menyimpan, dan lain-lain.
  • Code completion
    Fasilitas yang digunakan untuk melengkapi suatu perintah dengan otomatis, pemrogram tidak perlu menuliskan perintah secara lengkap, tetapi cukup bagian awal dari perintah tersebut, kemudian editor akan menampilkan perintah mana yang akan digunakan, untuk menuliskan secara lengkap di dalam editor. COde completion juga memberikan informasi untuk menuntun pemrogram menuliskan parameter apa yang harus dituliskan untuk suatu perintah atau fungsi.
  • Project dan file manager
    Fasilitas ini sangat diperlukan untuk memudahkan kita mengelola projek software yang kita kembangkan.
  • Multitab
    Fasilitas multitab yang dimaksud di sini adalah kita dapat melakukan penyuntingan beberapa file dalam satu window aplikasi. Kita dapat berpindah menuju file-file yang sedang disunting, cukup dengan mengklik nama file yang ditampilkan pada tab aplikasi.
  • Code folding 
    Fasilitas code folding adalah fasilitas yang dibutuhkan untuk membuat suatu program ditampilkan secara ringkas, suatu prosedur atau fungsi yang ada dalam file yang sedang disunting (edit), tidak perlu ditampilkan secara utuh, cukup namanya saja yang ditampilkan. Jika pemrogram ingin tahu isinya secara lengkap, pemrogram dapat mengklik tanda + untuk menampilkannya. Untuk mengembalikan menjadi bentuk ringkas (hanya nama saja), pemrogram dapat mengklik tanda -.

Editor yang menarik untuk digunakan dan memenuhi keempat kriteria di atas adalah scite (Windows dan Linux), yang menggunakan Scyntilla, engine editor teks. Sedangkan untuk  yang editor lainnya, umumnya belum memiliki fasiltias code folding, beberapa contoh adalah :

  • di Windows :
  • di Linux
    • quanta, sudah ada dalam package KDE, jika kita menggunakan Gnome sebagai windows manager, maka kita cukup memasang komponen KDE-libs dan QT saja.

Penulis sendiri lebih banyak menggunakan tswebeditor untuk membuat program PHP, JavaScript, atau pun ASP.