Bunele mele practici – General

1. Comentariile – blestem și binecuvântare

Comentariile bune sunt o artă. Gândite cu grijă, sunt un dar; adesea însă scrise în zadar.

Codul autodocumentat nu înseamnă „fără comentarii”. Codul ar trebui să exprime singur, cât se poate de bine, cum; comentariile completează de ce, constrângerile care nu sunt evidente și contractul unui API.

Urmează câteva exemple de cod autodocumentat, precum și de comentarii bune și proaste.

Un argument des întâlnit este că comentariile se învechesc ușor. De fapt, problema aceasta se aplică la fel de bine numelor de variabile și de metode!

Au – nu face niciodată asta:

int age = 32; // set the value of the age integer to 32

Cod autodocumentat: nume potrivite pentru variabile înseamnă jumătate din treabă

Așa nu:

var dateTime = DateTimeUtil.getNow();

Așa da:

var now = DateTimeUtil.getNow();

Încă un exemplu:

Așa nu:

User user = this.getBruce();

Așa nu:

// testing user without permission
User user = this.getBruce();

Așa da:

User userWithoutPermission = this.getBruce();

Cod autodocumentat: nume potrivite pentru metode

Așa nu:

public String sanitizeInput(String input) {
    // replace underscore with spaces
    return input.replaceAll("_", " ");
}

Așa da:

public String replaceUnderscoreWithSpaces(String input) {
    return input.replaceAll("_", " ");
}

Cod autodocumentat: metode private

Așa nu: metoda îl obligă pe cititor să descifreze în același timp validarea, calculul și regula de business.

public Invoice createInvoice(Order order, Customer customer) {
    if (order.items().isEmpty()) {
        throw new IllegalArgumentException("Order needs at least one item");
    }

    BigDecimal subtotal = order.items().stream()
            .map(item -> item.unitPrice().multiply(BigDecimal.valueOf(item.quantity())))
            .reduce(BigDecimal.ZERO, BigDecimal::add);
    BigDecimal discount = customer.isPremium()
            ? subtotal.multiply(new BigDecimal("0.10"))
            : BigDecimal.ZERO;

    return new Invoice(order.id(), subtotal, discount, subtotal.subtract(discount));
}

Așa da: metoda publică povestește fluxul. Metodele private și stateless denumesc fiecare intenție în parte și își fac dependențele vizibile prin parametri și valori returnate.

public Invoice createInvoice(Order order, Customer customer) {
    requireItems(order);
    BigDecimal subtotal = calculateSubtotal(order.items());
    BigDecimal discount = loyaltyDiscountFor(customer, subtotal);

    return invoiceFor(order, subtotal, discount);
}

private static void requireItems(Order order) {
    if (order.items().isEmpty()) {
        throw new IllegalArgumentException("Order needs at least one item");
    }
}

private static BigDecimal calculateSubtotal(List<OrderItem> items) {
    return items.stream()
            .map(item -> item.unitPrice().multiply(BigDecimal.valueOf(item.quantity())))
            .reduce(BigDecimal.ZERO, BigDecimal::add);
}

private static BigDecimal loyaltyDiscountFor(Customer customer, BigDecimal subtotal) {
    return customer.isPremium()
            ? subtotal.multiply(new BigDecimal("0.10"))
            : BigDecimal.ZERO;
}

private static Invoice invoiceFor(
        Order order,
        BigDecimal subtotal,
        BigDecimal discount
) {
    return new Invoice(order.id(), subtotal, discount, subtotal.subtract(discount));
}

Nu orice linie are nevoie de propria metodă. Se extrage un gând coerent, care poate fi denumit precis. Nume precum processData() sau handleStuff(), în schimb, nu aduc nimic.

Regula de bază: comentează de ce se întâmplă ceva, nu ce se întâmplă

Este clar ce se întâmplă aici:

public Duration retryDelay(int retryCount) {
    long seconds = Math.min(1L << retryCount, 60);
    return Duration.ofSeconds(seconds);
}

Dar de ce se întâmplă?

Mai bine:

public Duration retryDelay(int retryCount) {
    // Cap the delay so an outage never blocks queued jobs for more than one minute.
    long seconds = Math.min(1L << retryCount, 60);
    return Duration.ofSeconds(seconds);
}

Încă un exemplu din viața reală. Sunt prezentate metodele care afișează și ascund spinnerul de încărcare Ajax. Numai că sunt patru metode. De ce, nu e chiar clar la prima vedere:

function showAjaxLoader() {
    $('.layout-ajax-loader').children().first().show();
}

function hideAjaxLoader() {
    $('.layout-ajax-loader').children().first().hide();
}

function suppressAjaxLoader() {
    getOnlyElementByClassOrNull('layout-ajax-loader').style.display = 'none';
}

function releaseAjaxLoader() {
    getOnlyElementByClassOrNull('layout-ajax-loader').style.display = '';
}

Metodele par toate foarte asemănătoare și par să manipuleze cumva vizibilitatea prin CSS. Cu un scurt comentariu, cazurile de utilizare devin imediat clare:

showAjaxLoader: function() {
    $('.layout-ajax-loader').children().first().show();
},

hideAjaxLoader: function() {
    $('.layout-ajax-loader').children().first().hide();
},

// take the control from primefaces and don't allow the spinner to show, no matter what
suppressAjaxLoader: function() {
    getOnlyElementByClassOrNull('layout-ajax-loader').style.display = 'none';
},

// reset the state after hiding, to give the control back to primefaces
releaseAjaxLoader: function() {
    getOnlyElementByClassOrNull('layout-ajax-loader').style.display = '';
},

Încă un exemplu:

Așa nu:

/**
 * Sets the tool tip text.
 *
 * @param text  the text of the tool tip
 */
public void setToolTipText(String text) {}

Așa da:

/**
 * Registers the text to display in a tool tip. The text
 * displays when the cursor lingers over the component.
 *
 * @param text  the string to display. If the text is null,
 *              the tool tip is turned off for this component.
 */
public void setToolTipText(String text) {}

Discuție din workshopul din 2021-06-21: Opinia împărtășită de toți dezvoltatorii a fost că Javadoc ar trebui evitat în general (un coșmar al parametrilor, mereu învechit și greu de întreținut) și folosit doar când un parametru chiar are nevoie de explicații suplimentare sau când altfel ar trebui citită toată metoda, care e lungă.

Excepția de la regula de bază: comentează ce se întâmplă – aici e recomandat

Atunci când lizibilitatea devine mult mai bună, pentru că altfel codul nu ar fi clar:

let isAlwaysAllowedKey = (
    e.which === 8  || /* BACKSPACE */
    e.which === 35 || /* END */
    e.which === 36 || /* HOME */
    e.which === 37 || /* LEFT */
    e.which === 38 || /* UP */
    e.which === 39 || /* RIGHT*/
    e.which === 40 || /* DOWN */
    e.which === 46 || /* DEL*/
    e.ctrlKey === true && e.which === 65 || /* CTRL + A */
    e.ctrlKey === true && e.which === 88 || /* CTRL + X */
    e.ctrlKey === true && e.which === 67 || /* CTRL + C */
    e.ctrlKey === true && e.which === 90   /* CTRL + Z */
)

Comentarii – înjurăturile din codul kernelului Linux

Și, la final, o poveste amuzantă din kernelul Linux – numărul tuturor înjurăturilor din codul sursă:

https://www.vidarholen.net/contents/wordcount/#fuck*,shit*,damn*,idiot*,retard*

Spor la scris comentarii!

2. Metodele private din rutinele mari de program sunt periculoase

Atenție! În lumea orientată pe obiecte de azi există întotdeauna multe metode private. De obicei, asta nu e o problemă. Devine una abia atunci când aceste metode accesează câmpuri, adică starea (state), și se află în rutine mari. Astfel de submetode ar trebui să fie private și stateless. Altfel au dezavantajul că, apelate separat, pot provoca adesea neplăceri. Dezvoltatorii vor ajunge să apeleze submetoda. Stările ilegale sunt una dintre principalele cauze ale bugurilor. Un articol interesant pe această temă, despre câteva afirmații ale lui John Carmack (id Software, Doom) și despre faptul că în aplicațiile în care codul trebuie să fie foarte stabil (de exemplu în zborurile spațiale) subrutinele sunt adesea interzise, ceea ce face codul mai determinist: http://number-none.com/blow/john_carmack_on_inlined_code.html

Povestea aceasta se aplică doar parțial lumii moderne, stateless, Java/Spring, dar oferă totuși un bun motiv de reflecție.