Panduan Menulis Komentar Kode yang Baik

• Peran komentar kode:

  • Komentar kode tidak hanya menjelaskan ‘apa yang dilakukan kode yang kita tulis’, tetapi juga mendokumentasikan pertimbangan seperti keputusan desain dan trade-off
  • Dengan demikian, komentar menjelaskan ‘apa yang dikerjakan penulis kode, dan mengapa melakukannya seperti itu’
  • Komentar kode membantu membagikan konteks keputusan yang diambil selama proses penulisan kode di masa lalu
  • Ini menyampaikan informasi tentang kode yang sulit diungkapkan hanya melalui kode itu sendiri

• Pentingnya komentar kode:

  • Komentar inline yang ditempatkan sebelum kode yang kompleks menghemat waktu pengembang lain yang akan membaca kode tersebut nanti
  • Seiring proyek berkembang, menyisakan konteks keputusan kode yang diambil di masa lalu akan membantu pengembang lain.
  • Jika kode kompleks, setidaknya perlu ada komentar inline satu baris di depannya
  • Ada batasan jika ingin menyampaikan beragam informasi, termasuk konteks keputusan kode, hanya melalui kode itu sendiri

• Cara menulis komentar kode yang baik:

  1. Tulis dengan ringkas
     • Tulis komentar hanya saat benar-benar perlu, dengan memuat informasi yang esensial
       • Saat kode menjadi kompleks dan tidak terhindarkan
       • Saat menambahkan detail untuk meningkatkan presisi
       • Saat konteks tidak ada (misalnya ketika menggunakan kode dari repositori atau paket lain)
     • Kurangi kebingungan dan ambiguitas dalam komentar, serta berikan konteks dan informasi yang berguna
  2. Gunakan komentar TODOs/FIXMEs
     • Komentar TODOs/FIXMEs adalah cara untuk menunjukkan bahwa ‘bagian tertentu dari kode belum selesai dikerjakan atau perlu diperbaiki’
     • Tulis di depan fungsi seperti “TODO: fitur XX perlu ditambahkan”
     • Saat menulis kode lalu terpikir ‘bagian ini harus ditinjau lagi nanti’ atau ‘fitur ini harus dikembangkan di kemudian hari’, cara ini dapat digunakan untuk mencatat dan melacak hal-hal terkait
     • Extension yang berguna untuk digunakan: TODO Highlight
  3. Jangan membela kode dengan komentar
     • Daripada menambahkan komentar sebagai pembelaan untuk kode yang salah atau tidak jelas, lebih baik tulis ulang kodenya
     • Ada kode yang memang perlu dijelaskan dengan komentar, tetapi ada juga kode yang harus berbicara melalui ‘kode itu sendiri’ tanpa bergantung pada komentar
  4. Manfaatkan AI
     • Dengan menggunakan generator komentar AI, Anda dapat membuat komentar dalam format yang konsisten sesuai standar tertentu
     • Konsistensi komentar di seluruh proyek dapat dipertahankan, sehingga keterbacaan kode meningkat
     • Generator komentar AI yang layak digunakan: Readable

[penza1]

Kalau terasa perlu menulis komentar,
mungkin ada baiknya mempertimbangkan dulu apakah kodenya sendiri sebenarnya kurang tepat.

Komentar yang tidak lagi berjalan seiring dengan umur dan fungsi kode bisa menimbulkan kebingungan bagi developer yang nanti membacanya, atau bahkan bagi diri kita sendiri.

Walaupun konteks masa lalu sudah tidak relevan dengan kondisi sekarang atau bahkan pernah menyebabkan kesalahan,
kalimat yang menjelaskan konteks lama itu bisa membuat kita ragu untuk memperbaiki kondisi saat ini, atau malah memutar untuk menyelesaikannya dengan struktur lain,
dan pada akhirnya justru memicu lebih banyak kesalahan..

Dari pengalaman saya, tidak banyak komentar yang benar-benar bisa menjelaskan kenapa sesuatu dulu benar tetapi sekarang salah....

[ironlung]

Terima kasih telah membagikan pendapat yang berharga. Setelah memikirkan pendapat yang Anda bagikan, saya merasa bahwa demi perkembangan kode, perlu juga ada upaya untuk dengan cermat mempertanyakan kembali apakah komentar benar-benar diperlukan. :)

[aqqnucs]

https://youtu.be/Bf7vDBBOBUA?si=0-v44x48-rlVsYCq

Sambil menonton ini, saya juga berusaha agar tidak menulis komentar secara berlebihan

[ironlung]

Terima kasih sudah membagikan video yang bagus! :)

[iamchanii]

Menurut saya, sekalipun jalannya sudah dibangun dengan sangat baik, rambu penunjuk arah tetap mutlak diperlukan. Karena itu, belakangan ini saya berusaha membiasakan diri menulis komentar.

[ironlung]

Terima kasih telah membagikan insight Anda di kolom komentar. Setelah memikirkan apa yang Anda sampaikan, saya jadi kembali merenungkan bahwa komentar juga merupakan bagian penting dari technical writing, sehingga prinsip-prinsip dasar penulisan perlu ditinjau lagi. :)

[balak]

Menurut saya, yang terbaik adalah menulis kode agar tetap bisa dipahami meskipun tanpa komentar.

[ironlung]

Ya, saya juga merasa yang terpenting adalah setia pada dasar-dasarnya terlebih dahulu. Terima kasih atas komentarnya. :)