Perchè dire, la mia funzione è di tipo IFly piuttosto che dire che è tipo di aereo

Penso che la tua confusione derivi dal fatto che hai chiamato la tua interfaccia IFly . Qualsiasi libro di programmazione recente consiglia di non denominare le interfacce con I in primo piano. Dai alla tua interfaccia un nome appropriato.

Nel tuo esempio specifico sarebbe un po 'più difficile farlo, ma prendiamo questa situazione:

• L'interfaccia è: FlyingObject
• Implementazione1: Airplane implements FlyingObject
• Implementazione 2: Helicopter implements FlyingObject
• Implementazione3: UFO implements FlyingObject

Se lo fai e provi a scrivere una documentazione per questo, sarà abbastanza chiaro che cosa significhi StartFlying on FlyingObject .

In alcuni casi estremi, quando è impossibile trovare l'astrazione appropriata, puoi nominare la tua interfaccia con un nome concreto come Foo e con l'implementazione FooImplementation o FooImpl .

UPDATE: Ovviamente dipende sempre da ciò che stai documentando e da come. Se documenti la tua logica aziendale, puoi semplicemente dire che qualsiasi FlyingObject ha un metodo startFlying() . La tua logica aziendale non creerà quegli oggetti, quindi non ti importa di cosa sono esattamente. Di fatto, ciò rende le cose molto più chiare una volta che si documenta che la logica aziendale può utilizzare qualsiasi oggetto che abbia il metodo startFlying() e connetti tale conoscenza all'interfaccia. Non ti interessa chi crea Airplane o Helicopter . Tutto quello che sai e documenta dal punto di vista della logica aziendale è che puoi iniziare a volare se hai un oggetto capace di farlo.

D'altra parte se si documentano le vostre fabbriche o qualunque logica avete che decide quale tipo di oggetto volante creare, lì potete documentare qualcosa come 'Aereo, Elicottero, ecc. devono implementare FlyingObject, altrimenti non possono prendere tu in Giappone '.

Spero che questo aggiornamento chiarisca tutta la domanda che stavi chiedendo.

Dire StartFlying() è un metodo / funzione in IFly . La documentazione dovrebbe includere:

• Come trovare IFly, come lo spazio dei nomi (.net o Java) / file header (ad esempio C ++) e file (come un assembly nel file .Net o JAR in Java).
• Specificare ciò che il chiamante deve fornire, come gli argomenti del metodo e i loro valori consentiti,
• Cosa deve fare l'implementatore, come le modifiche ad altre proprietà o i valori restituiti.
• Gestione degli errori, quali le eccezioni generate e in quali condizioni.
• Requisiti di sicurezza. Ad esempio, l'utente deve essere membro del gruppo Pilots ?
• Collegamenti a interfacce simili (ad esempio IWalk , IRun )
• Link a un esempio o panoramica

Potresti includere collegamenti o riferimenti a classi che implementano IFly , come Bird e Aeroplane , ma questo può essere manuale e, quindi, soggetto a omissioni o errori di copia e incolla.

Perché descrivere StartFlying() in IFly in Bird o Aeroplane ? StartFlying() è stato estratto in un'interfaccia per standardizzare l'accesso a funzionalità simili in classi disparate. Ciò significa che altre classi potrebbero implementarlo in futuro oltre Bird e Aeroplane , sia all'interno della tua biblioteca che all'esterno.

Fai riferimento alla documentazione di IFly nella documentazione per Bird e Aeroplane , ma questi dovrebbero includere anche dettagli specifici dell'implementazione. Aeroplane , ad esempio, potrebbe richiedere IsFueled() per essere vero, e includerlo in IFly potrebbe confondere.