codestyle; एनोटेशन से पहले या बाद में javadoc लगाएं?

Question

मुझे पता है कि यह मुद्दों की सबसे महत्वपूर्ण बात नहीं है, लेकिन मुझे सिर्फ एहसास हुआ कि मैं घोषणा से पहले या बाद में javadoc टिप्पणी ब्लॉक डाल सकता हूं। एक कोडिंग मानक के रूप में हम क्या अपनाना चाहेंगे?

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

    @Autowired
    /**
     * This is a javadoc comment after the annotation
     */
    private MyOtherClass other;
}

Answer 1

एनोटेशन से पहले, एनोटेशन कोड है कि "वर्ग" के अंतर्गत आता है। आधिकारिक दस्तावेज में javadoc के साथ उदाहरण देखें ।

यहाँ एक और उदाहरण मुझे एक अन्य आधिकारिक जावा पेज में मिला :

/**
 * 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) {
    ...
}

Comments

यहां ब्याज के अलावा - एनोटेशन विधि के लिए अन्य क्वालिफायर के समान लाइन पर है। मैंने ऐसा पहले कभी नहीं देखा है, लेकिन यह सुझाव देता है कि एनोटेशन को एक विधि के लिए अन्य क्वालीफायर की तरह व्यवहार किया जाना चाहिए, और इस तरह से, javadoc को इससे पहले निश्चित रूप से जाना चाहिए।

— आर्टऑफवर्फ

यदि आप कुछ एनोटेशन-भारी जैक्सन का उपयोग कर रहे हैं तो उसी एनोटेशन को एक ही लाइन पर रखना हाथ से जल्दी निकल सकता है। मैंने प्रत्येक एनोटेशन को खुद की एक लाइन पर रखा।

— डब्ल्यूडब्ल्यू।

Answer 2

मैं पहले से दिए गए जवाबों से सहमत हूं।

एनोटेशन कोड का हिस्सा होते हैं जबकि javadoc प्रलेखन का हिस्सा होता है (इसलिए नाम)।

इसलिए मेरे लिए यह कोड भागों को एक साथ रखने के लिए उचित है।

Answer 3

यह सब पठनीयता के लिए आता है। मेरी राय में विधि / क्षेत्र के ऊपर एनोटेशन के साथ कोड अधिक पठनीय है।

Answer 4

कोडिंग मानक के अलावा, ऐसा लगता है कि javadoc टूल javadoc टिप्पणियों को संसाधित नहीं करता है यदि उन्हें घोषणाओं के बाद रखा जाता है। अन्यथा ठीक काम करता है।

Answer 5

मैं उपरोक्त सभी बातों से सहमत हूं। यह दूसरों के लिए मददगार हो सकता है कि IntelliJ (Idea) की कोड शैली टेम्प्लेट दोनों ही सकारात्मक रूप से विफल हो जाती हैं (जब @ सही तरीके से निर्दिष्ट किया जाता है, तो यह चेतावनी देता है) और गलत तरीके से नकारात्मक (जब @throws निर्दिष्ट नहीं होता है, लेकिन RestEasy शैली का उपयोग करते समय होना चाहिए) एनोटेशन। मैंने अपने javadocs को बाकी सब चीजों से ऊपर रखा, फिर एनोटेशन, फिर कोड।

बग रिपोर्ट यहां देखें: https://youtrack.jetbrains.com/issue/IDEA-220520