Ambiguità di nomi di metodi apparentemente chiari nelle API

3

(La domanda è indipendente dalla lingua, ma per illustrare il punto, ho scritto gli esempi in C #.)

Dire che sto provando a modellare il comportamento dei "componenti" che comunicano tramite "porte".

Potrei modellarlo come:

public interface Component
{
    int  Read(int portID, byte[] buffer);
    int Write(int portID, byte[] buffer);
}

e forse implementare l'interfaccia come:

public class MyComponent : Component
{
    private class Port
    {
        int  Read(byte[] buffer) { ... }
        int Write(byte[] buffer) { ... }
        void DoSomethingComplex()
        {
            this.Read(...);
            // ...
            this.Write(...);
        }
    }
    private Dictionary<int, Port> ports;
    public override int  Read(int portID, byte[] buffer) { ports[portId]. Read(buffer); }
    public override int Write(int portID, byte[] buffer) { ports[portId].Write(buffer); }
}

Abbastanza semplice, ma considera ciò che ti aspetti Read e Write da fare:
Dal punto di vista di un estraneo, sembra naturale che Read legga i dati di la porta del componente in il buffer specificato. Tuttavia, come un insider che sta chiamando this.Read(...) , è davvero quello che ti aspetti? O ti aspetteresti che i dati vengano letti dal buffer nella porta ?

La mia domanda è duplice:

  1. Non è stata fornita documentazione aggiuntiva, quale significato di Read e Write è più intuitivo?

  2. Come posso denominare ragionevolmente queste funzioni in modo che l'intento sia chiaro senza la necessità di ulteriore documentazione?
    (Ovviamente, posso chiamarli ReadFromPortIntoBuffer e WriteToPortFromBuffer o qualcosa del genere, ma uno spera in nomi più succinti.)

posta Mehrdad 12.04.2015 - 08:24
fonte

1 risposta

4

Assegnare nomi alle cose è difficile. Ma nella mia esperienza, l'ambiguità come questa può quasi sempre essere risolta usando un nome un po 'più verboso nel posto giusto. I nomi dei metodi alternativi che hai suggerito sono davvero brutti; in questo esempio la mia prima scelta sarebbe quella di rinominare i parametri:

public interface Component
{
    int  Read(int portID, byte[] outputBuffer);
    int Write(int portID, byte[] inputBuffer);
}

Anche se @rwong ha sottolineato, se questo particolare esempio è codice reale, l'obiettivo dovrebbe essere quello di assomigliare a un C # Stream standard il più possibile.

Per quanto riguarda la "direzione" più intuitiva per la lettura / scrittura, non credo che nessuno dei due sia. In effetti, la mia preferenza personale sarebbe un metodo di lettura che restituisce le cose che ha appena letto, e nessun "parametro di output" in entrambi i metodi (imo quelli sono solo una brutta soluzione per la mancanza di efficiente / complesso / più valori di ritorno in molte lingue). Sono sicuro che potresti trovare un sacco di persone che affermano che leggere per o leggere da sono i significati predefiniti "ovvi", a seconda di quali flussi / lettori / scrittori / lingue con cui hanno più familiarità.

    
risposta data 12.04.2015 - 10:52
fonte