Selamat siang kawan-kawan, berjumpa lagi dengan saya sang mantan auditor. Kali ini saya mau posting masalah comments.

Hari ini saya belajar comments, apa itu comments? Dari yang sudah saya baca, comments itu hal yang sepele tapi punya manfaat yang luar biasa, yaitu untuk mendokumentasikan program atau code yang telah kita tulis.

Coba bayangkan Anda sudah capek-capek nulis ratusan atau bahkan ribuan baris code, menemukan sebuah terobosan baru, tapi tanpa ada keterangan apa-apa masalah code yang sudah Anda tulis. Kemudian Anda disibukkan oleh pekerjaan lain selama beberapa lama, setahun misalnya, tanpa melirik sedikitpun code-code yang sudah anda ciptakan. Sampai pada akhirnya pekerjaan Anda selesai dan Anda bisa kembali pada code-code Anda. Ketika dibuka Anda akan bingung dan berfikir
Alhasil Anda pun stres sendiri dan ujung-ujungnya memutuskan untuk mengulang pekerjaan yang sudah bertahun-tahun dikerjakan.

Dengan comments kita bisa memberikan penjelasan untuk setiap code yang kita buat agar nanti suatu saat jika kita membuka kembali code tersebut setelah sekian lama dianggurkan kita akan dengan mudah mengerti apa yang sudah kita kerjakan. Atau misalnya ketika kita bekerja dalam sebuah tim untuk membangun sebuah aplikasi maka rekan satu tim kita dapat mengerti apa dan bagaimana code kita bekerja sehingga mereka bisa menggunakan code kita tanpa harus dikit-dikit nanya kita.

Cara kerja comments sangat sederhana, setiap karakter (apapun) yang ada di dalam jangkauan comments akan diabaikan oleh komputer (compiler) sehingga tidak dieksekusi menjadi bagian dari program.

Dalam Java ada 3 macam comments yang bisa kita pakai untuk mendokumentasikan pekerjaan kita.
1. Single-Line Comments
Single-Line Comments mencakup satu baris (namanya juga single-line) dalam program kita yang akan diabaikan oleh komputer. Untuk membuat Single-Line Comments dimulai dengan "//" (tanpa petik) kemudian diikuti komen (keterangan) kita. Meneruskan contoh pada postingan sebelumnya saya akan memasukan comment ke dalam code HelloWorld saya

package greetings;

public class HelloWorld {

    public static void main(String[] args) {
        System.out.println("Hello World"); //Untuk menge-print satu baris tulisan "Hello World"
        System.out.println(Math.sqrt(3*3 + 4*4)); //Output = jarak koordinat (0,0) dan (3,4)
    }

}

Gunakan Single-Line Comments untuk memberikan penjelasan yang singkat namun bermakna. Jangan gunakan Single-Line Comments untuk memberikan penjelasan yang tidak perlu, seperti

package basic;

public class Comments{

    int i = 10; //Variable i untuk menyimpan data berupa primitive int

    public static void main(String[] args) {
        System.out.println(i);
    }

}

2. Multiline Comments
Jika Single-Line Comments hanya mencakup satu baris maka Multiline Comments mencakup lebih dari satu baris. Untuk membuat Multiline Comments dimulai dengan "/*" (tanpa petik) kemudian diikuti keterangan atau komen dan diakhiri dengan "*/" (tanpa petik).

package basic;

public class Comments {

   /*
    * Anggap saja ini adalah sebuah
    * method ga sederhana, sehingga
    * saya perlu memberikan penjelasan
    * agak panjang
    */
    double someMethod(int par1, int par2){
        return par1 * par2;
    }
}

Dalam Multiline Comment tidak diperbolehkan memasukan Multiline Comment lagi di dalamnya karena akan menyebabkan error. Contoh Multiline Comment terlarang:

package basic;

public class Comments {

   /*
    * Penjelasan pertama
    * /* terus ada penjelasan lagi */  << TERLARANG
    */
    double someMethod(int par1, int par2){
        return par1 * par2;
    }
}

Tanda * sebelum tiap kalimat jangan dipusingkan, hanyalah untuk memperindah. :D

3. Javadoc Comments
Javadoc Comments ini sangat bermanfaat, terutama jika bekerja dalam sebuah tim. Dengan Javadoc Comments kita tidak perlu membuka file Java atau class ketika ingin mengakses sebuah method dalam class tersebut. Semua keterangan yang kita berikan pada method tersebut akan muncul jika diakses dari class lain. Javadoc Comments dimulai dengan "/**" (lagi, tanpa petik) kemudian diikuti penjelasan dan diakhiri dengan "*/".

package basic;

public class Comments { 
   /** 
    * @param par1 sebuah angka dengan data type primitive int
    * @param par2 sebuah angka dengan data type primitive int
    * @return par1 * par2 sebuah angka dengan data type primitive double hasil perkalian par1 dan par2
    * @author Harry Marwanto
    * @category latihan
    * @since 28 January 2015
    */
    double someMethod(int par1, int par2){
        return par1 * par2;
    }

}

Kemudian beberapa bulan kemudian saya membuat class baru dengan nama Main dan ingin mengakses someMethod-nya class Comments dari class Main

package basic;

public class Main {
 
   public static void main(String[] args){
       Comments com = new Comments();
       com.someMethod(3, 2);
   }

}

Yang akan terjadi ketika ketikan code saya sampai pada "com.som" adalah Eclipse akan memunculkan sebuah window yang berisi informasi mengenai someMethod yang telah kita tulis di class Comments seperti berikut

Berikut adalah daftar identifier yang dipakai dalam Javadoc Comments:
1. @author untuk menjelaskan nama penulis program
2. @deprecated untuk menjelaskan bahwa code atau method sudah kadaluarsa, menekankan kepada pengguna code bahwa code atau method tersebut sebaiknya tidak digunakan lagi
3. @param untuk menjelaskan parameter apa yang digunakan/dibutuhkan oleh program
4. @see untuk memberikan referensi lain (see also....)
5. @since untuk memberitahukan kapan program tersebut direlease
6. @return untuk memberitahukan jenis data type yang diberikan oleh method, dalam contoh di atas adalah berupa data type primitive double
7. @throws menjelaskan exception apa yang dilempar oleh method

Oke, sekian dulu curhatan saya tentang Comments, jangan sungkan untuk protes jika ada yang salah dengan postingan saya, semoga curhatan saya ini tidak merusak mood Anda hari ini. Terima kasih sudah mampir, sampai jumpa di curhatan berikutnya. :D