Java zavádza markdown syntax do komentárov

JavaDoc komentáre slúžia na dokumentáciu kódu pre vývojárov a na automatické vygenerovanie dokumentácie vo forme HTML súborov. Ide o mix HTML značiek a špeciálnych @ Java tagov vnorených vo viacriadkových komentároch.

JEP 467: Markdown Documentation Comments zavádza markdown syntax pre JavaDoc komentáre. Plánuje sa to pre Javu 23. Nová syntax výrazne zjednoduší a sprehľadní písanie komentárov. Markdown je v súčasnosti masovo rozšírený značkovací jazyk pre tvorbu rôzneho typu dokumentácie.

Môže sa to zdať ako málo významná zmena, ale komentáre tvoria veľkú časť kódu. Nová syntax bude mať tak významný dopad na celkovú ergonómiu kódu.

Pre porovanie, takto vyzerá komentár v jazyku C#:

/// <summary>
/// Generate an array of random reviews.
/// </summary>
/// <param name="product">The name of the product.</param>
/// <param name="lines">The number of reviews to be generated.</param>
/// <returns>A string array of user reviews.</returns>
public string[] Reviews(string product = "product", int lines = 2)
{
    return Enumerable.Range(1, lines)
        .Select(_ => this.Review(product))
        .ToArray();
}

Je to neprehľadné a nezmyselne zahustené XML značkami. Ide o jednu z mála vecí, ktorú C# podľa môjho názoru horšie implementoval.

/**
 * Set custom SSL socket factory
 * @param sslSocketFactory custom SSL socket factory
 * @return this Connection, for chaining
 */
Connection sslSocketFactory(SSLSocketFactory sslSocketFactory);

Takto vyzerá súčasný JavaDoc komentár. Je výrazne prehľadnejší, ako jeho C# náprotivok. S markdown syntaxou sa stanú komentáre ďalej viac prehľadnými. Ako je v posledných rokoch dobrým zvykom, očakávam podobnú zmenu aj pre .NET. Obe platformy sa výrazne medzi sebou inšpirujú.