Tips koding bersama dengan tim
Bagaimana cara meningkatkan efektivitas koding bersama dengan tim?
Dalam proyek pembuatan aplikasi atau perangkat lunak, seringkali programmer membentuk sebuah tim untuk melakukan pengembangan. Setiap anggota memiliki tugas pengerjaannya masing-masing, yang seringkali tidak berhubungan secara langsung. Namun dalam pengerjaannya, terkadang tim memiliki masalah karena setiap anggota tim tidak menggunakan atau tidak tahu cara menggunakan dokumentasi dalam code mereka. Tidak jarang anggota lain tidak paham setiap fungsi yang telah dikerjakan, sehingga anggota harus meluangkan waktu untuk menjelaskan setiap fungsi yang dikerjakan agar mampu digunakan.
Problem seperti ini mampu memperlambat proses pengembangan sehingga dibutuhkan sebuah solusi yang membuat setiap anggota tim mampu memahami isi koding tanpa perlu menanyakan kegunaan dari setiap fungsi. Solusi ini dapat berupa dokumentasi koding. Banyak orang tahu bahwa dokumentasi koding merupakan sesuatu yang penting, namun tidak tahu cara menggunakannnya.
Dalam solusi ini, saya akan membahas dalam bahasa Swift, bahasa milik Apple. Pemrograman Swift dilakukan dalam program Xcode, sebuah program milik Apple untuk pengembangan iOS, MacOS, dan lain-lain. Pada Xcode sendiri, developer Apple telah menyediakan built-in plugin untuk membuat dokumentasi dalam koding, seperti comments, mark comment, dan code documentation. Selain itu, ada beberapa hal yang perlu diperhatikan, seperti penamaan fungsi dan variabel, access modifier, dan
1. Comments
Dalam Swift, terdapat 2 buah tipe comment, yaitu tipe regular comments dan documentation comments. Perbedaannya terletak pada apakah comment tersebut mampu dibaca oleh Swift Compiler sebagai dokumentasi atau tidak. Regular comments merupakan comment yang menggunakan double-slash (//) untuk line comments dan (/* … */) sebagai block comments. Biasanya regular comments digunakan untuk catatan programmer terhadap beberapa bagian kodingan. Contoh:
Sedangkan untuk documentation comments, menggunakan triple-slash (///) untuk line comments dan (/** … */) untuk block comments. Contoh:
Pada documentation comment, Swift Compiler akan menjadikan comment yang terletak di atas sebuah kodingan sebagai dokumentasi kodingan tersebut. Kamu dapat melihatnya dengan cara tekan Option, lalu klik pada nama fungsinya, maka kamu akan melihat seperti gambar di bawah.
Selain menggunakan option + klik fungsi, kamu bisa melihat dokumentasi melalui Quick Help di bagian inspector (di sebelah kanan editor xcode).
2. Mark Comments
Setiap tahunnya, Apple selalu menambahkan fungsi pada Xcode dan Swift agar setiap kodingan di dalamnya lebih mudah untuk dikelola. Sesuai namanya, mark comments digunakan untuk menandakan bagian-bagian tertentu dalam kodingan agar mudah dibaca dan dikelola pada Xcode. Penggunaan mark comments menggunakan “//MARK:” di atas bagian koding yang ingin dituju. Selain itu, mark comments juga bisa ditambahkan garis pemisah di dalamnya agar terlihat lebih mudah. Cara pemakaiannya adalah dengan cara menambahkan tanda hubung menjadi “//MARK: -”.
Dengan menggunakan mark comments, kamu akan dipermudah oleh Xcode karena setiap mark comments akan tercatat dalam Quick Jump Bar pada bagian atas Xcode sehingga kita mampu melompat ke bagian yang diinginkan dengan cepat.
Garis merah di atas menunjukkan Quick Jump Bar yang ada pada setiap tampilan editor yang ada. Lalu, apabila kamu meng-klik salah satu bagian akhir pada quick navigation yang ada, maka akan muncul tampilan seperti tampilan di sebelah kanan yang berisikan setiap variabel, method, class, dan mark yang telah dipasang. Apabila kamu menggunakan mark tanpa tanda hubung, maka pada quick navigation hanya terlihat tanda mark dan catatannya, contoh pada gambar “Membuat Random TIPS TRIK berdasarkan list yang dipunyai”. Sedangkan pada mark dengan tanda hubung, akan terlihat garis pemisah pada setiap bagiannya, contoh pada gambar “Data Manipulation”.
Sejak Xcode 11, sistem mark comments juga dapat dilihat melalui minimap editor sehingga mempermudah programmer untuk melompat ke salah satu bagian tanpa perlu membuka quick navigation.
Tampilan minimap dapat dilihat dengan shortcut Command + Control + Shift + M atau melalui editor options. Berdasarkan gambar di atas, setiap mark yang dibuat akan diperlihatkan dengan tulisan yang lebih besar. Dengan minimap yang sama, kamu juga bisa melompat ke method yang diinginkan.
Selain mark, ada juga “//FIXME:” untuk menandakan adanya bug pada kodingan dan juga “//TODO:” untuk menandakan bagian yang harus dikerjakan ke depannya. Cara menggunakan kedua fungsi ini sama dengan mark.
3. Code Documentation
Dalam membuat dokumentasi kode, Apple mengimplementasikan markdown dari CommonMark sebagai keyword extension. Penggunaan markdown dalam file dengan extension .swift menggunakan documentation comments (lihat part. 1). Sebagai referensi, kamu bisa melihat penggunaan markdown pada Apple Developer Markup Overview. Code Documentation ini lebih sering digunakan pada penjelasan suatu fungsi (function atau method) untuk menjelaskan kegunaannya.
Saya menyimpulkan pada markup documentation bahwa ada 5 hal yang sering dipakai pada code documentation, yaitu
- Description: penjelasan singkat tentang kegunaan method tersebut.
- Parameter: penjelasan mengenai setiap parameter yang ada, bisa berupa aturan penggunaan parameter tersebut, seperti “value harus lebih besar dari 0”.
- Returns: penjelasan mengenai pengembalian data hasil proses dari method tersebut, seperti “berupa dictionary <String, Int>”.
- Warning: penjelasan mengenai peringatan penggunaan method tersebut, seperti “method belum dicoba”
- Notes: poin-poin penting yang harus diperhatikan ketika programmer lain ingin menggunakannya.
Berikut adalah contoh penggunaan markdown dalam function:
Kalian bisa menyalin template di atas untuk kalian gunakan di setiap function yang dibuat.
Penggunaan option-option yang tersedia pada markdown bersifat optional, sehingga kamu tidak dipaksa untuk mengisinya. Isilah yang diperlukan saja. Untuk urutannya, paling atas pasti merupakan summary atau description. Setelah itu, urutan setiap markdown tidak menjadi masalah. Contoh:
Pada contoh di atas, baris pertama merupakan deskripsi dari kegunaan function tersebut. 2 baris berikutnya merupakan bagian discussion yang biasa digunakan untuk penjelasan lebih lanjut dari deskripsi. Setelah itu, apabila kita ingin melihat dokumentasi yang ada, kita dapat melihatnya melalui shortcut Option + klik function atau melalui bagian quick help, sehingga akan terlihat seperti gambar di bawah:
Additional Notes
Ketika menggunakan code documentation, daripada mengetik dokumentasi dari scratch atau salin tempel pada setiap fungsi, ada baiknya kita menyimpannya ke dalam code snippet. Cara memasukkannya ke dalam code snippet cukup mudah. Berikut adalah langkah memasukkannya:
Pertama, silahkan copy template di atas ke dalam Xcode kalian, lalu pilih kodenya dan klik kanan. Setelah itu klik pilihan “Create Code Snippet”, seperti yang ditunjukkan pada gambar di bawah.
Pada tampilan code snippet, kamu bisa memberikan nama, deskripsi, dan code completion. Code completion di sini merupakan kata yang akan menjadi trigger untuk pemanggilan data pada code snippet. Pada contoh ini, saya menggunakan kata “documentation”. Kamu juga bisa membuat code snippet mark comment jika mau.
Apabila sudah, kamu bisa menutup window tersebut, dan mencobanya pada editor. Kamu bisa memanggil code snippet yang sudah terpasang berdasarkan code snippet yang telah disiapkan.
Kesimpulan
Ketiga cara di atas merupakan cara yang sering digunakan oleh programmer professional dan sering dilupakan oleh programmer pemula. Cara tersebut dapat mempermudah dalam mengelola kodingan yang telah dibuat. Dengan menambah dokumentasi, orang awam pun mampu memahami kegunaan dari setiap fungsi yang dibuat.
Selain ketiga cara di atas, ada beberapa hal yang sebaiknya juga diperhatikan oleh programmer pemula, yaitu penamaan variabel dan fungsi. Gunakan penamaan variabel yang mudah dipahami, lebih baik menggunakan penamaan yang panjang dibandingkan menggunakan penamaan yang disingkat yang terkadang menyulitkan pembaca untuk memahami.
Semakin lengkap dokumentasi, semakin efektif pula pekerjaan sebuah tim programmer.
Selamat mencoba …
