codestyle; ek açıklamadan önce veya sonra javadoc koymak?

184

Sorunların en hayati olmadığını biliyorum, ama javadoc yorum bloğunu ek açıklamadan önce veya sonra koyabileceğimi fark ettim. Bir kodlama standardı olarak neyi kabul etmek isteriz?

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

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

— Paul McKenzie
kaynak

191

Ek açıklamadan önce, ek açıklama sınıfa "ait" kod olduğu için. Resmi belgelerde javadoc ile ilgili örneklere bakın .

İşte başka bir resmi Java sayfasında bulduğum rastgele örnek :

/**
 * 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
kaynak

8

Ayrıca burada da ilgi çekici - açıklama, yöntemin diğer niteleyicileriyle aynı satırda. Daha önce yapıldığını hiç görmedim, ancak ek açıklamaların bir yöntem için diğer niteleyiciler gibi ele alınması gerektiğini ve javadoc'un kesinlikle bundan önce gitmesi gerektiğini gösteriyor.

— ArtOfWarfare

8

Jackson gibi ek açıklama ağırlıklı bir şey kullanıyorsanız aynı ek açıklamaları aynı satıra koymak çabucak elden çıkabilir. Her ek açıklamayı kendi satırına koydum.

— WW.

17

Verilen cevaplara katılıyorum.

Ek açıklamalar kodun bir parçası iken, javadoc dokümantasyonun bir parçasıdır (dolayısıyla ad).

Bu yüzden benim için kod parçalarını bir arada tutmak mantıklı.

— perdian
kaynak

11

Her şey okunabilirliğe iniyor. Bence kod, doğrudan yöntemin / alanın üzerindeki Ek Açıklamalar ile daha okunabilir.

— Robby Göleti
kaynak

11

Kodlama standardının yanı sıra, ek açıklamalardan sonra yerleştirilirse, javadoc aracının javadoc yorumlarını işlemediği anlaşılıyor. Aksi takdirde iyi çalışır.

— shadrik
kaynak

0

Yukarıdakilerin hepsine katılıyorum. RestEasy stilini kullanırken IntelliJ (Idea) 'ın kod stili şablonlarının hem hatalı pozitif (@throws doğru belirtildiğinde, uyarır) hem de yanlış negatif (@throws belirtilmediğinde, ancak olması gerekir) başarısız olması diğerlerine yardımcı olabilir. ek açıklamalar. Javadoclarımı diğer her şeyin üstüne koydum, sonra ek açıklamaları, sonra kodlamayı.

Hata raporuna buradan bakın: https://youtrack.jetbrains.com/issue/IDEA-220520

— Max P Magee
kaynak