Praktik terbaik dalam penulisan komentar dan dokumentasi

20

Mengomentari saat ini lebih mudah dari sebelumnya. Di Java, ada beberapa teknik yang bagus untuk menghubungkan komentar ke kelas, dan Java IDEs bagus dalam membuat shell komentar untuk Anda. Bahasa seperti Clojure bahkan memungkinkan Anda untuk menambahkan deskripsi fungsi dalam kode fungsi itu sendiri sebagai argumen.

Namun kami masih hidup di zaman di mana sering ada komentar usang atau buruk yang ditulis oleh pengembang yang baik - Saya tertarik untuk meningkatkan kekokohan dan kegunaan komentar saya.

Khususnya saya tertarik pada Java / Clojure / Python di sini, tetapi jawaban tidak perlu spesifik bahasa.

Apakah ada teknik baru yang memvalidasi komentar dan secara otomatis mendeteksi komentar "tipis" (misalnya komentar dengan angka ajaib, kalimat tidak lengkap, dll.) Atau komentar yang salah (misalnya, mendeteksi variabel yang salah eja atau sejenisnya).

Dan yang lebih penting: Apakah ada "kebijakan komentar" yang diterima atau strategi di luar sana? Ada banyak saran di luar sana tentang cara kode - tetapi bagaimana dengan "bagaimana berkomentar?"

java python clojure comments jayunit100
sumber

Jawaban:

40

  • Nama / dokumentasi harus memberi tahu Anda apa yang Anda lakukan.

  • Implementasi harus memberi tahu Anda bagaimana melakukannya.

  • Komentar harus memberi tahu Anda mengapa Anda melakukannya seperti yang Anda lakukan.

ratchet freak
sumber
6
komentar juga harus memberi tahu Anda mengapa Anda tidak melakukannya dengan cara lain - yaitu pilihan desain yang penting - karena pengelola masa depan tidak akan memiliki informasi ini sebaliknya.
2
Saya percaya ada banyak kali komentar harus mengatakan APA yang Anda lakukan juga. Gagasan ini hanya komentar "mengapa" adalah anti-pola menurut saya. Ini adalah mitos bahwa Anda dapat menulis semua kode dengan cukup jelas sehingga setiap programmer dapat memahaminya sekilas, dan pengalaman saya adalah sebagian besar programmer yang berpikir mereka menulis kode bersih tidak. Itu sama dengan mengatakan, "Saya tidak harus menyebutkan fungsi ini secara deskriptif karena siapa pun bisa membaca kode dalam fungsi untuk melihat apa fungsinya." - itu juga tidak masuk akal, kan?
dallin
2
@dallin jika kode Anda tidak jelas tentang apa yang dilakukannya; pertimbangkan refactoring itu. kalau tidak tambahkan komentar yang menjelaskan mengapa itu diterapkan seperti itu (yang kebetulan juga menjelaskan bagaimana lebih baik). Perbandingan Anda dengan nama deskriptif adalah apel / jeruk, nama deskriptif memperjelas di mana fungsi tersebut digunakan , dan Anda mungkin tidak memiliki akses ke kode sumber fungsi.
ratchet freak
@allin: "Ini adalah mitos bahwa Anda dapat menulis semua kode dengan cukup jelas sehingga setiap programmer dapat memahaminya sekilas", Paman Bob ingin berbicara dengan Anda. - "Saya tidak perlu menyebutkan fungsi ini secara deskriptif karena siapa pun dapat membaca kode dalam fungsi untuk melihat apa fungsinya." sedang melakukan!
klaar
14

Ini mungkin kontroversial, tetapi saran saya adalah menulis komentar BEBERAPA mungkin. Gunakan nama kelas yang bagus, jelas, nama variabel dan nama metode. Tulis kode Anda dengan cara yang paling jelas yang Anda bisa; dan menganggap ini sebagai atribut paling penting dari kode Anda (selain itu memenuhi persyaratannya). Hanya tulis komentar jika Anda telah membuat metode sejelas mungkin, dan Anda masih berpikir itu membutuhkan penjelasan lebih lanjut.

Dan memiliki praktik organisasi, bahwa setiap kali ada yang mengubah kelas dengan cara apa pun, mereka harus memastikan komentarnya masih benar.

Dawood berkata mengembalikan Monica
sumber
1
Ini adalah awal yang baik, tetapi saya pikir untuk memenuhi pertanyaan OP, Anda perlu menulis sesuatu yang membahas masalah aktualnya sehubungan dengan validasi otomatis.
Robert Harvey
2
+1 - Saya juga berpikir bahwa komentar hanya boleh digunakan untuk menjelaskan mengapa kode telah ditulis. Saya tahu apa yang harus if (a == b) then c();dilakukan, tetapi jika saya tidak tahu mengapa ia melakukannya - saat itulah komentar harus digunakan :)
Deco
Deco - Saya setuju sepenuhnya. Komentar baik ketika saya ingin memahami bagaimana metode tertentu cocok dengan proses secara keseluruhan. Dengan kata lain, MENGAPA Anda akan memanggil metode ini, atau MENGAPA melakukan apa yang dilakukannya.
Dawood mengatakan mengembalikan Monica
Selain membuat kode tertulis jelas, kita juga harus memastikan untuk mempertahankan (level kode) ide, pemikiran, dll. Menggunakan komentar TODO. Misalnya jika Anda melihat fungsi / kelas mampu menangani ukuran data saat ini dengan benar, tetapi berpotensi gagal menangani beban setelah 2 tahun, maka pastikan untuk menulis pengamatan Anda di sana menggunakan komentar TODO. Pengembang masa depan memang akan menghargai upaya Anda. Jangan pernah mencoba mencatat hal-hal ini dalam dokumen txt / word yang terpisah, saat menulis kode, tidak ada yang benar-benar merujuk dokumen tersebut.
TechCoze
lihat juga: "Komentar adalah bau kode"
agas
5

Saya tidak yakin tentang bahasa lain, tetapi python memungkinkan Anda untuk menulis dokumen yang merupakan bentuk komentar validasi diri. Tentu saja, mereka tidak boleh digunakan sebagai pengganti pengujian unit nyata, tetapi merupakan metode cepat dan mudah untuk mendokumentasikan fungsi tertentu yang mungkin tidak sejelas yang seharusnya. Mereka datang dengan manfaat tambahan karena dapat melakukan tes komentar untuk memverifikasi bahwa komentar masih benar (setidaknya sebagian dari mereka yang berisi tes).

Josh Smeaton
sumber
1
Dan Sphinx membandingkan kode dengan dokumentasi untuk memberikan metrik cakupan.
S.Lott
3

Salah satu lokasi yang paling otoritatif untuk menemukan cara menggunakan kode komentar untuk menghasilkan dokumentasi secara otomatis pasti adalah oksigen . Meskipun ada lebih banyak alat seperti itu dari saya.

Ini mendefinisikan standar penulisan komentar yang harus diikuti untuk secara otomatis menghasilkan dokumentasi. Namun, ini memberikan lebih banyak struktur tetapi tidak memvalidasi secara semantik; misalnya tidak dapat memeriksa apakah Anda telah menggunakan bahasa Inggris yang menyesatkan untuk menjelaskan tujuan suatu fungsi!

Sementara, ini adalah hal terbaik yang membuat komentar terstruktur, secara pribadi saya merasa ada lebih banyak dokumentasi yang diperlukan untuk membuat kode lebih mudah dikelola. Beberapa waktu lalu ada pertanyaan dalam P.SE Dapatkah kode menjadi dokumentasi dalam alat pengembang open source? Seberapa sering? Tentu saja, ini berlaku untuk proyek-proyek non-open-source juga.

Untuk membuat kode lebih dapat dipelihara - praktis lebih penting bahwa ada dokumentasi eksternal yang membantu membuat struktur cara memperlakukan kode, dan kemudian komentar di dalam kode harus dibatasi untuk melihat

Saya pikir, jika Anda ingin mendefinisikan kebijakan untuk penulisan komentar Anda harus memasukkan sebagai pendekatan holistik yang termasuk dalam standar pengkodean. Lihat ini: Apa yang bisa menjadi jebakan dalam memperkenalkan panduan gaya dan dokumentasi yang menghasilkan perangkat lunak dalam tim pengembangan?

Biasanya komentar kurang dari 5% dari kode. Dan dalam prakteknya sementara tinjauan kode itu sendiri menarik perhatian yang jauh lebih sedikit (lebih dari aspek-aspek pembangunan lainnya) praktis sulit sehingga komentar juga ditinjau.

Dipan Mehta
sumber
1
Saya tidak setuju dengan kalimat terakhir di sini. Saya baru saja menyelesaikan kontrak, bekerja di bawah pimpinan tim yang memberikan ulasan yang sangat rinci. Ulasannya selalu menyertakan komentar - bagaimana mereka diucapkan, apakah nama variabelnya benar, apakah mereka berisi semua informasi yang mungkin ingin diketahui oleh pengembang di masa depan. Tak lama kemudian, saya tahu apa yang dia harapkan untuk dilihat di setiap komentar, dan mampu menghasilkan komentar sesuai standarnya. Jadi, asalkan kebijakan organisasi memiliki ulasan kode, dan memasukkan komentar dalam tinjauan kode, maka itu akan terjadi.
Dawood mengatakan mengembalikan Monica
Ini biasanya satu-satunya jenis komentar yang saya tulis, terutama untuk metode untuk mendokumentasikan apa yang masuk dan apa yang keluar darinya (saya bekerja dengan bahasa yang diketik secara longgar).
DanMan
2

Apakah ada teknik baru yang memvalidasi komentar dan secara otomatis mendeteksi komentar "tipis" (misalnya komentar dengan angka ajaib, kalimat tidak lengkap, dll.) Atau komentar yang salah (misalnya, mendeteksi variabel yang salah eja atau sejenisnya).

Ada teknik yang sangat dikenal - ini disebut "review kode", dan memiliki saudara perempuan bernama "pair-programming". Jangan mengharapkan apa pun yang "otomatis" di sini.

Dan yang lebih penting: Apakah ada "kebijakan komentar" yang diterima atau strategi di luar sana? Ada banyak saran di luar sana tentang cara kode --- tapi bagaimana dengan "bagaimana berkomentar?"

"Kode selesai" tidak hanya berisi semua tentang cara membuat kode, tetapi juga bab tentang "cara mengomentari", terutama tentang cara menulis kode yang mendokumentasikan sendiri.

Doc Brown
sumber
+1 untuk Kode Selesai. Clean Code oleh Robert Martin juga memiliki bab yang bagus tentang penulisan pujian yang bermanfaat. Saya tidak yakin tentang dunia Java tetapi di dunia .NET kami memiliki Resharper, yang dapat 'secara otomatis' memvalidasi referensi ke elemen kode dalam komentar :)
MattDavey
0

Khusus untuk Java, satu sumber yang saya nikmati adalah Cara Menulis Komentar Doc untuk Perangkat Javadoc :

Dokumen ini menjelaskan panduan gaya, tag, dan konvensi gambar yang kami gunakan dalam komentar dokumentasi untuk program Java yang ditulis di Software Java, Sun Microsystems.

Dan Butir 44: Tulis komentar dokumen untuk semua elemen API yang terbuka :

Jika suatu API dapat digunakan, itu harus didokumentasikan. Dokumentasi API tradisional dihasilkan secara manual, dan menjaganya agar tetap sinkron dengan kode adalah tugas. Lingkungan pemrograman Java memudahkan tugas ini dengan utilitas Javadoc. Javadoc menghasilkan dokumentasi API secara otomatis dari kode sumber dengan komentar dokumentasi yang diformat khusus, lebih dikenal sebagai komentar dokumen.

dari Java Edisi 2 yang Efektif .

TELUR
sumber