Doporučené postupy v programování

# Doporučené postupy v programování

## Návrh API
        ### API · Proces návrhu · Obecné principy · Návrh tříd · Návrh metod

#### Lubomír Bulej
        ##### KDSS MFF UK

Notes:

Tyto slajdy čerpají primárně ze skvělé přednášky a slajdů o návrhu API
        a jeho důležitosti, kterou přednesl Joshua Bloch (dříve Sun, dnes Google)
        na JavaPolis 2005: 
        [How to Design a Good API & Why it Matters](https://www.infoq.com/presentations/effective-api-design)
        ([slajdy](https://d3s.mff.cuni.cz/files/teaching/nprg043/extras/bloch06-how_to_design_a_good_api-slides.pdf)).

V podstatě stejné poselství lze nalézt i v článku Michi Henninga
        v ACM Queue: [API: Design Matters](https://queue.acm.org/detail.cfm?id=1255422).

Zajímavá je také přednáška z konference JavaOne 2006 od Tima Boudreaua a
        Jaroslava Tulacha: [How to write API that will stand the test of time](https://ssw.jku.at/Teaching/Lectures/SpezialLVA/Modularity/apidesign.pdf).
        S tím souvisí pěkný tutorial o návrhu API na webu NetBeans:
        [How to Design a Module API](https://netbeans.apache.org/wiki/main/wiki/API_Design)
        a v neposlední řadě kniha Jaroslava Tulacha, z níž také čerpám
        – Practical API Design: Confessions of a Java Framework Architect,
        APress, 2008.

# Příklad: rozhraní `Select()` v C#

## Představa použití C# rozhraní v kódu serveru

```csharp stretch small
        int timeout = ...;
        ArrayList readList = ...; // sockets to monitor for reading
        ArrayList writeList = ...; // sockets to monitor for writing
        ArrayList errorList = ...; // sockets to monitor for errors

while (!done) {
          ArrayList checkRead = readList.Clone();
          ArrayList checkWrite = writeList.Clone();
          ArrayList checkError = errorList.Clone();
          Select(checkRead, checkWrite, checkError, timeout);

foreach (Socket socket in checkRead) {
            // deal with each socket ready for reading
          }

foreach (Socket socket in checkWrite) {
            // deal with each socket ready for writing
          }

foreach (Socket socket in checkError) {
            // deal with each socket that encountered an error
          }

if (checkRead.Count == 0 && checkWrite.Count == 0 && checkError.Count == 0) {
            // no sockets are ready -- timed out...
          }
        }
        ```

Notes:
        
        - socketů může být mnoho, ale množiny se celkem nemění
        - chyba nás většinou zajímá u socketů pro čtení nebo zápis
          - typicky se oba seznamy slučují, tady je navíc nutné eliminovat duplicitní sockety
        - funkce nemá návratovou hodnotu a ničí předané parametry
        - timeout je v mikrosekundách, max. timeout je asi 35 minut
          - není jasné jak čekat nekonečně dlouho

# Příklad: rozhraní `Select()` v C#

## Wrapper funkce `doSelect()`

```csharp stretch
        public static void doSelect(
          IList checkRead, IList checkWrite, IList checkError, int milliseconds
        ) {
          ArrayList readCopy;  // copies of the three parameters
          ArrayList writeCopy; // because Select() clobbers them
          ArrayList errorCopy;

if (milliseconds <= 0) {
            // simulate waiting forever
            do {
              ... // copy socket lists
              Select(readCopy, writeCopy, errorCopy, Int32.MaxValue);
            } while (!hasActiveSocket(readCopy, writeCopy, errorCopy));

} else {
            // handle finite timeouts
            int maxMilliseconds = Int32.MaxValue / 1000;

int remaining = milliseconds;
            while ((remaining > 0) && !hasActiveSocket(readCopy, writeCopy, errorCopy)) {
              int timeout = milliseconds > maxMilliseconds ? maxMilliseconds : milliseconds;
              ... // copy socket lists
              Select(readCopy, writeCopy, errorCopy, timeout * 1000);
              remaining -= timeout;
            }
            ... // copy the three lists back to original parameters
          }
        }
        ```

# Návrh API ## Proces návrhu

# Návrh API ## Obecné principy

# Obecné principy
        
        ## Snažte se o typovou a běhovou konzistenci

- vše co jde zapsat by mělo správně fungovat
          - ne vždy je možné toho dosáhnout
        - omezuje možnost nesprávného použití API

## Příklad: java.sql

```java stretch okay-code
          public interface Connection {
            ...
            public Savepoint setSavepoint();
            public void rollback(Savepoint sp);
            ...
          }

public interface Savepoint {
            public String getSavepointId();
            public String getSavepointName();
          }
          ```

</div>

```java stretch good-code
          public interface Connection {
            ...
            public Savepoint setSavepoint();
            ...

public interface Savepoint {
              public void rollback();
              public String getSavepointId();
              public String getSavepointName();
            }
          }
          ```

</div>
        </div>

</div>

# Návrh API ## Návrh tříd

# Doporučení pro návrh tříd

## Preferujte immutable třídy

- mutable objekty komplikují design a při sdílení se na ně nelze spolehnout
           
          ```java stretch bad-code
          HttpRequest req = new HttpRequest();
          req.setUrl("https://api.example.com");
          req.setMethod("POST");

sendAsync(req);
          req.setUrl("https://another.example.com");
          ```
        - pokud objekt představuje konfiguraci nebo výsledek, neměl by jít po vytvoření změnit

## Pozor na "teleskopické" konstruktory

- vytváření immutable objektů s mnoha volitelnými parametry
           
          ```java stretch bad-code
          HttpRequest req = new HttpRequest(
              "https://api.com", "POST", 5000, true, null, "Bearer token"
          );
          ```
        - v místě volání nepřehledné, náchylné k chybám

</div>

Notes:

Ve chvíli, kdy klientům vracíte z vašeho API nějaká data (nebo je od
        nich přijímáte k asynchronnímu zpracování), musíte zajistit, že vám je
        nezmění pod rukama. Třídy reprezentující stav nebo konfiguraci by měly
        mít pouze (nutné) gettery a veškerá data by měla být předána při konstrukci.

# Doporučení pro návrh tříd

## Zvažte použití vhodného nositele rozhraní

- interface – Java, ...
          - vícenásobná dědičnost, oddělení rozhraní a implementace, oddělení konceptů
          - problém s rozšiřováním pokud rozhraní implementuje klient – SPI
          - nemá konstruktor ani factory, může ho implementovat kdokoliv
          - není možné vynucovat sémantiku (co kdyby `String` byl interface?)

</div>
        <div class="fragment">

- final třída
          - podporuje různé úrovně přístupu, může poskytnout statické metody
          - lepší předpoklady pro evoluci – možno přidávat metody

</div>
        <div class="fragment">

- abstraktní třída?
          - může mít statické metody (ale to už interface také)
          - nepodporuje vícenásobnou dědičnost (signatur)
          - omezení přístupových práv (včetně konstruktoru)
            - poskytuje kontrolu nad tím, kdo může implementovat abstraktní metody

</div>

# Doporučení pro návrh tříd

## Význam modifikátorů u metod v API

<table class="real">
          <tr>
            <th>Modifikátory</th>
            <th>Primární význam</th>
            <th>Vedlejší významy</th>
          </tr>
          <tr class="fragment bad-code">
            <td><code>public</code></td>
            <td>Může být volána externími klienty.</td>
            <td>Může být předefinována v odvozených třídách.<br/>Může být volána z odvozených tříd.</td>
          </tr>
          <tr class="fragment bad-code">
            <td><code>public abstract</code></td>
            <td>Musí být implementována v odvozených třídách.</td>
            <td>Může být volána externími klienty.</td>
          </tr>
          <tr class="fragment good-code">
            <td><code>public final</code></td>
            <td>Může být volána externími klienty.</td>
            <td>Žádné.</td>
          </tr>
          <tr class="fragment bad-code">
            <td><code>protected</code></td>
            <td>Může být volána z odvozených tříd.</td>
            <td>Může být předefinována v odvozených třídách.</td>
          </tr>
          <tr class="fragment good-code">
            <td><code>protected abstract</code></td>
            <td>Musí být implementována v odvozených třídách.</td>
            <td>Žádné.</td>
          </tr>
          <tr class="fragment good-code">
            <td><code>protected final</code></td>
            <td>Může být volána z odvozených tříd.</td>
            <td>Žádné.</td>
          </tr>
        </table>

# Doporučení pro návrh tříd

## Transformace metod s vedlejšími významy
        <table class="real">
          <tr>
            <th>Původní kód</th>
            <th>Transformace</th>
          </tr>
          <tr class="fragment">
            <td>
              ```java bad-code
              public abstract void method();
              ```
            </td>
            <td>
              ```java good-code
              public final void method() {
                methodImpl();
              }

protected abstract void methodImpl();
              ```
            </td>
          </tr>

<tr class="fragment">
            <td>
              ```java bad-code
              public void method() {
                someCode();
              }
              ```
            </td>
            <td>
              ```java good-code
              public final void method() {
                methodImpl();
              }

protected abstract void methodImpl();
              protected final void someCode() {
              }
              ```
            </td>
          </tr>

<tr class="fragment">
            <td>
              ```java bad-code
              protected void method() {
                someCode();
              }
              ```
            </td>
            <td>
              ```java good-code
              protected abstract void method();
              protected final void someCode() {
              }
              ```
            </td>
          </tr>
        </table>

# Příklad: Kompozice jednoúčelových typů

## Klientské API, SPI, a API pro podtřídu v jedné třídě

```java stretch bad-code
        public abstract class AbstractSensor {
          private final int i2cAddress;

protected AbstractSensor (int address) {
            this.i2cAddress = address;
          }

// 1. API pro klienty
          public final double readTemperature () {
            return readFromHardware ();
          }

// 2. SPI poskytované podtřídou (implementace čtení)
          protected abstract double readFromHardware ();

// 3. Služba pro podtřídu (konfigurace)
          protected final int getI2cAddress () {
            return i2cAddress;
          }
        }
        ```

Notes:

- Třída má příliš mnoho zodpovědností.
        - Nutí autora "ovladače" dědit ze třídy, která drží stav.
        - Klientské API a SPI jsou ve stejné třídě, přičemž protected abstract
          metody SPI vyžadují, aby byla třída také abstract, zatímco pro
          klientské API je potřeba, aby byla třída final. Je nutné rozhraní
          oddělit a propojit při kompozici.
        - Klientské API a API pro rozšíření (podtřídu) sdílí stejný jmenný
          prostor, což znemožňuje nezávislý vývoj a komplikuje testování
          samotného hardwarového ovladače (nelze jej snadno testovat bez
          inicializace celé nadtřídy).

# Příklad: Kompozice jednoúčelových typů

## 1. část: Samostatné třídy pro SPI a API pro pluginy

```java stretch good-code
        // Služba pro SPI (konfigurace)
        public final class SensorContext {
          private final int i2cAddress;

SensorContext (int address) {
            this.i2cAddress = address;
          }

public int getI2cAddress () {
            return i2cAddress;
          }
        }

// SPI - rozhraní pro tvůrce pluginu.
        public interface SensorProvider {
          // Při inicializaci získá kontext s parametry.
          void initialize (SensorContext context);

double readFromHardware ();
        }
        ```

Notes:

Jasné rozhraní pro tvůrce pluginu. Plugin musí poskytnout
        initializační metodu, pomocí které je mu předán kontext
        poskytující služby pro plugin. To usnadňuje testování, protože
        můžeme ovladači poskytnout testovací kontext.

# Příklad: Kompozice jednoúčelových typů

## Použití odděleného API a SPI v testech

- SPI můžeme testovat odděleně od API

```java stretch
        public class SensorTest {
          @Test
          public void sensorWorksInIsolation() {
            DummyI2cSensor provider = new DummyI2cSensor();
            SensorContext context = new SensorContext(0x42);
            provider.initialize(context);

assertEquals(22.5, provider.readFromHardware());
          }

@Test
          public void sensorWorksThroughClientApi() {
            Sensor sensor = Sensor.create(0x42, new DummyI2cSensor());

assertEquals(22.5, sensors.readTemperature());
          }
        }
        ```

Notes:

První test ukazuje, že SPI můžeme testovat zcela izolovaně. Není nutné
        vytvářet klientskou API třídu, pouze dodáme "falešný" kontext.
        Druhý test ověřuje, že API správně deleguje volání na poskytovatele.

# Návrh API ## Návrh metod

# Příklad: nenuťte uživatele dělat zbytečnosti

## Java: serializace XML dokumentu

```java stretch bad-code
        import org.w3c.dom.*;
        import java.io.*;
        import javax.xml.transform.*;
        import javax.xml.transform.dom.*;
        import javax.xml.transform.stream.*;

// DOM code to write an XML document to a specified output stream.
        private static final void writeDoc(Document doc, OutputStream out) throws IOException {
          try {
            Transformer t = TransformerFactory.newInstance().newTransformer();
            t.setOutputProperty(
              OutputKeys.DOCTYPE_SYSTEM,
              doc.getDoctype().getSystemId()
            );
            t.transform(new DOMSource(doc), new StreamResult(out));
          } catch (TransformerException e) {
            throw new AssertionError(e); // Can’t happen!
          }
        }
        ```

Notes:

Příklad ukazuje na naprosto odbyté sbírání požadavků na API, protože
        serializace XML dokumentu je jedna z nejčastějších operací s XML/DOM
        API vůbec a v Javě je zcela zbytečně komplikovaná.

# Doporučení pro návrh metod

## Rozlišujte chyby programátora...

- Špatné použití API — nedodržení kontraktu (preconditions)
            - např. předání `null` tam, kde nesmí být
        - Cílem je rychlé selhání (fail-fast) a oprava kódu, nikoliv obsluha chyb
            - např. výjimky jako `IllegalArgumentException` nebo `IllegalStateException`

## ... a chyby uživatele

- Očekávatelné doménové chyby a problémy
            - např. platba zamítnuta, soubor neexistuje, uživatel zadal text místo čísla
        - Cílem je komunikace s uživatelem (případně opakování operace)
            - vraťte chybový objekt, nebo použijte specifické (dokumentované) doménové výjimky

</div>

Notes:

Pokud např. koncový uživatel zadá na příkazové řádce špatný vstup, není to
        chyba programátora, ale běžný stav, na který musí program umět reagovat
        (např. poukázat na chybu a vypsat nápovědu, nikoliv stack trace).