Apakah tipuan docblock mubazir saat menggunakan pengetikan yang ketat

Saya memiliki basis kode pribadi yang cukup besar yang telah berkembang selama sekitar sepuluh tahun sekarang. Saya tidak menggunakan phpDocumentor tetapi karena menggunakan bagian docblock telah menjadi standar dalam proyek open source, saya telah mengadopsi penulisan docblock untuk semua metode publik di repositori saya juga. Sebagian besar blok hanya berisi deskripsi kecil dan petunjuk tip untuk semua parameter dan tipe pengembalian.

Dengan kedatangan analisis statis, petunjuk jenis ini telah banyak membantu saya menemukan inkonsistensi dan kemungkinan bug. Akhir-akhir ini saya telah mengonversi seluruh basis kode (Sekarang berjalan di PHP7.2) untuk memiliki semua parameter dan mengembalikan nilai ketik-diisyaratkan di mana mungkin, menggunakan petunjuk jenis PHP. Dan sekarang saya bertanya-tanya ... Bukankah tipuan docblock ini berlebihan? Ia meminta sedikit kerja untuk menjaga semua dokumen tetap sinkron dengan kode yang selalu berubah dan karena mereka tidak menambahkan informasi baru, saya bertanya-tanya apakah lebih baik untuk menghapusnya atau tidak.

Di satu sisi, menghapus dokumentasi terasa buruk, bahkan ketika itu berlebihan. Di sisi lain, saya benar-benar merasa ingin melanggar hal-hal yang mengisyaratkan-tipe-sehari-hari yang Tidak-Ulangi-Sendiri-prinsip yang sudah tip-tip.

Informasi yang dapat ditemukan dalam kode tidak boleh digandakan dalam komentar.

Paling-paling, usaha yang sia-sia untuk membuat mereka tetap sinkron. Kemungkinan besar, mereka akan keluar dari sinkronisasi pada akhirnya. Pada titik itu, mereka hanya membingungkan.

Jika Anda melihat padanan DocBlock dalam bahasa yang diketik secara statis (mis. Java, C #), Anda akan menemukan bahwa komentar dokumen tidak mengandung informasi jenis. Sejauh ini terjadi dalam kode PHP Anda, saya sangat menyarankan untuk mengikutinya. Tentu saja, di mana petunjuk tipe tidak dapat diterapkan, komentar masih merupakan alternatif terbaik Anda.

Ini tidak relevan dengan PHP, tetapi informasi jenis duplikat dapat masuk akal ketika jenis disimpulkan secara implisit (misalnya Haskell).

Ya, docblock telah menjadi berlebihan dengan php 7.

Sebagian besar waktu dalam pengkodean dihabiskan untuk membaca, jadi harus membaca hal yang sama dua kali berdampak pada produktivitas Anda. Selain itu, mudah untuk melewatkan komentar penting yang sebenarnya.

Saya tidak menulis docblock lagi, kecuali ketika saya ingin mengetikkan petunjuk array jenis tertentu (misalnya @return int[]atau @param SomeStatus[] $statusList) atau ketika saya ingin menambahkan komentar tentang metode, parameter atau nilai pengembalian. Saya merasa penting untuk menonaktifkan pemeriksaan phpstorm yang dipicu ketika Anda tidak memiliki parameter alis dan mengembalikan tipe dalam docblock jika Anda memiliki docblock.

Kode dan dokumentasi biasanya memiliki audiensi yang berbeda: dokumentasi untuk pengguna fungsi itu. Mereka tidak harus melihat kode untuk memahami tipenya. Oleh karena itu, dokumentasi harus mencakup semua informasi yang diperlukan, termasuk tipe.

Dalam beberapa sistem, tidak perlu menentukan jenis parameter dalam dokumentasi karena jenisnya dapat diambil dari kode. PHPDoc bukan sistem seperti itu. Sebaliknya, @paramtag didokumentasikan itu

Ketika disediakan itu HARUS berisi Jenis untuk menunjukkan apa yang diharapkan

"Sedikit pekerjaan untuk menjaga agar semua dokumen tetap sinkron dengan kode yang selalu berubah" agak berkurang karena PHPDoc akan memeriksa petunjuk jenis dokumentasi terhadap petunjuk jenis kode. Ini adalah semacam analisis linting / statis, jadi jadikan generasi dokumentasi Anda sebagai bagian dari jalur uji otomatis Anda.

Pertanyaan lain yang mungkin ingin Anda tanyakan pada diri sendiri adalah mengapa fungsi-fungsi ini didokumentasikan dalam detail ini ketika mereka “terus berubah”. Motivasi yang biasa adalah membuat manual referensi HTML dari antarmuka Anda. Tetapi jika dokumentasi tidak pernah dibaca di luar IDE, atau jika Anda tidak memiliki antarmuka yang stabil di mana dokumentasi masuk akal, maka rincian dokumentasi tidak diperlukan atau bahkan menyesatkan. Mungkin lebih baik menulis ringkasan, dan menunda dokumen lengkap sampai Anda tiba di desain yang stabil.