Dihentikan vs Diturunkan di JavaDoc?

11

Dalam JavaDoc X509Certificate getSubjectDN()untuknya menyatakan:

Diturunkan , diganti oleh getSubjectX500Principal ().

Saya terbiasa melihat usang dalam metode yang tidak boleh digunakan lagi, tetapi tidak direndahkan. Saya menemukan laporan bug tentang kasus khusus ini di mana ditutup dengan komentar:

Ini bukan bug. "Tidak berlaku lagi" dimaksudkan untuk digunakan hanya dalam kasus-kasus serius.

Saat kami menggunakan metode yang sudah usang , tindakan umum yang disarankan adalah berhenti menggunakan metode.

Jadi apa tindakan yang disarankan ketika suatu metode ditandai sebagai Diturunkan ?

java terminology javadocs Jacob Schoen
sumber
2
Wow. Saya sudah membaca jawabannya, dan meskipun saya yakin mereka secara teknis benar, 'Diturunkan' adalah kata yang buruk untuk digunakan. Mereka seharusnya menggunakan 'Berkecil hati'. Tidak perlu meludahi kode; peringatan sudah cukup.
Eric King
@Eric King Saya agak merasakan hal yang sama. Saya berpikir lebih dalam garis bahwa jika berkecil hati hanya mencela itu.
Jacob Schoen

Jawaban:

9

Definisi merriam-Webster tentang penghinaan menunjukkan:

1: untuk menyerang reputasi: mencemarkan nama baik <merendahkan lawan seseorang>
2: untuk menyangkal pentingnya atau validitas dari: meremehkan <merendahkan prestasi mereka>

Berdasarkan apa yang tertulis dalam bug lain yang terkait, pencemaran nama baik / belittle tampaknya sesuai dengan maksud kata-kata yang digunakan dalam javadocs - ID Bug: 4959744 Merendahkan X509Certificate.getSubjectDN () & co :

The metode getSubjectDN () dan getIssuerDN () di X509Certificate dan getIssuerDN () di X509CRL yang bermasalah . Mereka mengembalikan kelas yang tidak ditentukan mengimplementasikan antarmuka java.security.Principal, yang memiliki spesifikasi yang sangat longgar.

Karena tidak ada spesifikasi tambahan hadir dalam metode getSubjectDN () dan getIssuerDN (), maka diperbolehkan untuk implementasi mengembalikan kelas khusus implementasi yang sewenang-wenang. Pengalaman dunia nyata telah menunjukkan bahwa ini adalah kasus yang mengakibatkan non-portabilitas atau tidak dapat diandalkannya kode. Untuk alasan kompatibilitas, spesifikasi untuk metode tersebut tidak dapat diubah dan harus dianggap tidak dapat diselamatkan.

Metode penggantian getSubjectX500Principal () & co yang mengembalikan instance kelas X500Principal yang terdefinisi dengan baik ditambahkan dalam JDK 1.4. Implementasi dari metode-metode tersebut telah dirancang untuk menghindari semua masalah seperti ini. Namun, metode baru ini menderita kekurangan paparan dan pemrogram terus menggunakan metode getSubjectDN () & co.

Untuk mengubahnya, metode getSubjectDN () dan getIssuerDN () yang lama harus dihentikan. Itu akan memastikan bahwa pengembang yang menggunakan metode ini menerima peringatan waktu kompilasi ....

EVALUASI

... Penghentian dianggap tidak pantas dalam kasus ini. Sebaliknya, komentar peringatan ditambahkan ke JavaDoc .

Fakta bahwa membaca Bug ID 5008142 telah membuat Anda bingung tentang hal-hal yang "direndahkan" ini lebih mirip kesalahan pengembang yang menanganinya.

Mereka seharusnya menemukan bug 4959744 dan merujuknya dalam evaluasi mereka, alih-alih pernyataan yang kabur "dimaksudkan untuk digunakan hanya dalam kasus-kasus serius". Mereka mungkin bahkan dapat ditutup sebagai duplikat, dengan justifikasi seperti "Penghentian telah dipertimbangkan, dievaluasi dan ditolak demi pencemaran nama baik per Bug ID 4959744" .

Paling tidak mereka bisa merujuk Bug ID 4959744 (mungkin bersama dengan 4638294 ) di bidang Laporan Terkait (disebut Lihat Juga di bugs.sun.com iirc lama) dari pelacak bug mereka. Bahwa ini belum dilakukan membuat satu tersangka bahwa mereka tidak mencari masalah terkait sama sekali.

agas
sumber
1
@FrustratedWithFormsDesigner Bagian tersulit adalah mencari cara memasukkan "direndahkan" di halaman pencarian oracle sehingga hasilnya disaring ke "bugs.sun.com". Sisanya mudah, saya baru saja memeriksa beberapa hasil pencarian yang muncul. "Merendahkan" adalah kata yang cukup bagus untuk mencari :)
agas
1
Lihat saya telah menggunakan Google untuk menemukan yang pertama, tetapi itu tidak memberi saya yang lain. Saya mungkin seharusnya terlihat lebih keras. Terima kasih
Jacob Schoen
@ Jonschoen Saya pikir ini bukan kesalahan Anda; Saya memperluas jawaban tentang itu
nyamuk
4

Setelah menggali lagi saya bisa menemukan posting blog yang disebut Deprecation in JDK . Ini pada dasarnya menyatakan bahwa hal-hal yang ditandai usang dianggap berbahaya untuk digunakan, dan bahwa ada beberapa hal yang tidak dianjurkan.

Kebijakan umum untuk beberapa rilis fitur adalah bahwa komponen JDK inti hanya ditandai sebagai usang jika mereka secara aktif berbahaya. Jika menggunakan kelas atau metode hanya keliru, itu biasanya tidak cukup untuk mendapatkan tanda usang.

Dia menyebutkan bahwa saat ini ada cara untuk menandai item sebagai tidak disarankan untuk digunakan, tetapi mereka mungkin akhirnya menambahkan cara untuk melakukan ini.

Pada titik tertentu, saran semacam ini mungkin diformalkan dengan fasilitas "denigrasi" yang tidak berbahaya dan tidak usang yang didasarkan pada kombinasi tag javadoc dan anotasi untuk memungkinkan pemeriksaan terprogram untuk penggunaan elemen API yang kurang berbahaya ini.

Meskipun saya tidak dapat menemukan hal lain secara khusus tentang keputusan untuk menggunakan istilah yang diremehkan ini tampaknya cukup dekat. Dan berdasarkan hal ini tampaknya tindakan yang harus diambil pengembang sama dengan usang , jangan gunakan metode ini.

Jacob Schoen
sumber