codestyle; menempatkan javadoc sebelum atau setelah anotasi?

184

Saya tahu bahwa itu bukan masalah yang paling vital, tetapi saya baru sadar bahwa saya dapat meletakkan blok komentar javadoc sebelum atau setelah anotasi. Apa yang ingin kita adopsi sebagai standar pengkodean?

/**
 * This is a javadoc comment before the annotation 
 */
@Component
public class MyClass {

    @Autowired
    /**
     * This is a javadoc comment after the annotation
     */
    private MyOtherClass other;
}
java coding-style annotations javadoc code-documentation Paul McKenzie
sumber

Jawaban:

191

Sebelum anotasi, karena anotasi adalah kode yang "milik" kelas. Lihat contoh dengan javadoc dalam dokumentasi resmi.

Inilah contoh acak yang saya temukan di halaman resmi Java lainnya :

/**
 * Delete multiple items from the list.
 *
 * @deprecated  Not for public use.
 *    This method is expected to be retained only as a package
 *    private method.  Replaced by
 *    {@link #remove(int)} and {@link #removeAll()}
 */
@Deprecated public synchronized void delItems(int start, int end) {
    ...
}
Peter Jaric
sumber
8
Yang juga menarik di sini - penjelasannya ada di jalur yang sama dengan kualifikasi lainnya untuk metode ini. Saya belum pernah melihat itu dilakukan sebelumnya, tetapi tampaknya menyarankan bahwa anotasi harus diperlakukan seperti kualifikasi lainnya untuk suatu metode, dan karena itu, javadoc pasti harus pergi sebelum itu.
ArtOfWarfare
8
Menempatkan anotasi yang sama pada baris yang sama dapat dengan cepat keluar dari tangan jika Anda menggunakan sesuatu yang berat seperti anotasi seperti Jackson. Saya menempatkan setiap anotasi pada barisnya sendiri.
WW.
17

Saya setuju dengan jawaban yang sudah diberikan.

Anotasi adalah bagian dari kode sementara javadoc adalah bagian dari dokumentasi (karenanya namanya).

Jadi bagi saya itu masuk akal untuk menjaga bagian-bagian kode bersama-sama.

perdian
sumber
11

Semuanya bermuara pada keterbacaan. Menurut pendapat saya kode lebih mudah dibaca dengan Anotasi langsung di atas metode / bidang.

Robby Pond
sumber
11

Selain dari standar pengkodean, alat javadoc tampaknya tidak memproses komentar javadoc jika ditempatkan setelah anotasi. Sebaliknya berfungsi dengan baik.

Sharrik
sumber
0

Saya setuju dengan semua hal di atas. Mungkin bermanfaat bagi orang lain bahwa templat gaya kode IntelliJ (Idea) gagal baik positif palsu (ketika @throws ditentukan dengan benar, itu memperingatkan) maupun negatif palsu (ketika @throws tidak ditentukan, tetapi seharusnya) ketika menggunakan gaya RestEasy penjelasan. Saya meletakkan javadocs saya di atas segalanya, lalu anotasi, lalu kode.

Lihat laporan bug di sini: https://youtrack.jetbrains.com/issue/IDEA-220520

Max P Magee
sumber