Javadoc

Javadoc Java kodunu avtomatik olaraq HTML sənədlərə çevirən standart sənədləşdirmə alətidir. Kodla yanaşı saxlanan mətn + tag-lar sayəsində API istifadəsi aydınlaşır, IDE-lərdə (hover, completion) zəngin yardım göstərilir.

Niyə Javadoc?

• Komandadaxili bilik paylaşımı
• Public API sabitliyinin qorunması
• IDE inteqrasiyası (IntelliSense / Quick Doc)
• Mürəkkəb biznes məntiqində niyyətin açıqlanması

Harada Yazılır?

Yer	Sənədləşdir
Public Class / Interface	Ümumi məqsəd, invariants
Public Method	Məntiq, parametrlər, edge case davranışı
Public Field (lazımdırsa)	Mənası, vahidi
Package-info.java	Paket səviyyəli konsept
Module-info.java	Modul təsviri

Əsas Tag-lar

Tag	Məqsəd
@param	Parametr izahı
@return	Geri dönüş dəyəri
@throws / @exception	Atıla bilən Exception səbəbi
@since	Versiya məlumatı
@deprecated	İstifadə etmə xəbərdarlığı
@see	Əlaqəli sinif/metod
@implNote	Implementation detalları
@implSpec	Contract tələbləri (override edənlər üçün)
@author	Müəllif
@version	Versiya nömrəsi
@serial	Serializable sahələr

Sadə Nümunə

Koda bax

/**
 * İstifadəçi hesabı üçün əsas domain modeli.
 * @implNote Immutable deyil – setter-lər vasitəsilə dəyişir.
 */
public class Account {
    /** Unikal identifikator (DB auto increment). */
    private Long id;

    /** İstifadəçi login adı (unikal). */
    private String username;

    /** SHA-256 + salt ilə hash-lənmiş parol. */
    private String passwordHash;

    /**
     * Parolu yeniləyir.
     * @param rawPassword Plain-text parol (məsuliyyət: çağıran tərəf boş olmamalıdır)
     * @throws IllegalArgumentException əgər parol boşdursa
     */
    public void updatePassword(String rawPassword){
        if(rawPassword == null || rawPassword.isBlank()) {
            throw new IllegalArgumentException("Boş parol");
        }
        this.passwordHash = PasswordUtil.hash(rawPassword);
    }
}

Stil Qaydaları

Qayda	İzah
Birinci cümlə qısa	İlk cümlə summary kimi HTML-də çıxır
Imperativ stil	"Gets the value" əvəzinə "Get value" ilə başlama
Texniki detallar @implNote	API contract ilə implementation qarışmasın
@param sırası	Metoddakı real parametr sırası
Tag-lar ardıcıllığı	@param → @return → @throws → digər

@deprecated İstifadəsi

Koda bax

/**
 * @deprecated Yerinə {@link #hashPassword(String)} istifadə edin.
 */
@Deprecated(since = "2.1", forRemoval = true)
public String legacyHash(String p){
    // köhnə alqoritm
    return md5(p);
}

@implSpec vs @implNote

Tag	Məqsəd
@implSpec	Override edənlər üçün contract şərtləri
@implNote	Internal detalları izah edir

Koda bax

/**
 * Returns cached total.
 * @implSpec Override edənlər cache invalidation qaydasını qoruyub saxlamalıdır.
 * @implNote Daxildə LRU cache istifadə olunur.
 */
public int total(){ return cache.getOrCompute(...); }

Method Davranışını Aydın Yazmaq

Pis:

@return siyahı

Yaxşı:

@return Heç bir uyğun element tapılmazsa boş (null deyil) siyahı

Edge Case-lərin Sənədləşdirilməsi

Mövzu	Nəyi qeyd et
Null icazəsi	Parametr null ola bilərmi?
Thread-safety	Sinif thread-safe-dirmi?
Mutation	Dönən kolleksiya dəyişdirilə bilərmi?
Performance	Çox böyük inputda komplekslik
Exception	Hansı şərtdə atılır

Generic Metodlar

Koda bax

/**
 * Birinci elementi qaytarır.
 * @param <T> siyahının element tipi
 * @param list emal ediləcək siyahı (null olmamalıdır)
 * @return birinci element
 * @throws IllegalArgumentException əgər siyahı boşdursa
 */
public static <T> T first(List<T> list){
    if(list.isEmpty()) throw new IllegalArgumentException("Boş");
    return list.get(0);
}

Package Sənədləşməsi

package-info.java faylı ilə paket konseptləri, arxitektura qaydaları.

Koda bax

/**
 * Payment domeninin əsas axınları:
 * <ul>
 *   <li>Ödəniş yaradılması</li>
 *   <li>Risk yoxlanışı</li>
 *   <li>Kompensasiya prosesləri</li>
 * </ul>
 */
package com.example.payment;

Modullar (Java 9+)

module-info.java daxilində module səviyyəli Javadoc.

Avtomatik Javadoc Yaratmaq

Maven:

Koda bax

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>3.6.0</version>
      <configuration>
        <source>17</source>
        <failOnError>true</failOnError>
      </configuration>
      <executions>
        <execution>
          <goals><goal>jar</goal></goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Gradle:

Koda bax

tasks.withType(Javadoc) {
    options.encoding = 'UTF-8'
    options.addBooleanOption('html5', true)
    failOnError = true
}

IDE Praktikası

IDE Feature	Faydası
Live templates	Standart tag skeleton
Inspectors	Boş @param, uyğunsuz tag xəbərdarlığı
Quick Doc	Hover ilə tez oxu

Sual-Cavab

Sual	Cavab
Bütün private metodları sənədləşdirim?	Yox, sadəcə kompleks məntiq varsa inline comment
@author yazım?	Komanda siyasətindən asılı
Niyə failOnError?	CI-də keyfiyyət düşməsinin qarşısı
@deprecated nə zaman?	Funksionallıq planlı silinməyə gedirsə

Ən Yaxşı Təcrübələr

• Public API-ləri 100% document et
• "Nə edir" fokuslan, "Necə edir" deyil (implementation dəyişə bilər)
• Throw olunan hər custom exception üçün səbəb yaz
• Təkrar ifadələrdən qaç (məs: metod adı + description eyni cümlə)
• Dönən kolleksiyanın boş/null davranışını açıq de

Tipik Səhvlər

Problem	Nəticə
Copy-paste doc	Yanlış/yanıltıcı məlumat
Boş @param tag-lar	IDE warning seli
Implementation leak	Daxili detallar dəyişəndə doc yalnış olur
Return davranışı qeyri-müəyyən	Consumer yanlış istifadə

Növbəti Addım

Kod keyfiyyəti ilə əlaqəli daha geniş yanaşma üçün: design-patternler/2.clean-code və test strategiyası üçün testing/unit-testing sənədlərinə bax.