La documentazione in OOP dovrebbe evitare di specificare se un "getter" esegue o meno un calcolo?

Il programma CS della mia scuola evita qualsiasi menzione di programmazione orientata agli oggetti, quindi ho fatto alcune letture per conto mio per integrarlo - in particolare, la costruzione di software orientata agli oggetti di Bertrand Meyer.

Meyer sottolinea ripetutamente che le classi dovrebbero nascondere quante più informazioni possibili sulla loro implementazione, il che ha senso. In particolare, sostiene ripetutamente che gli attributi (cioè le proprietà statiche, non calcolate delle classi) e le routine (proprietà delle classi che corrispondono alle chiamate di funzione / procedura) dovrebbero essere indistinguibili l'uno dall'altro.

Ad esempio, se una classe Personha l'attributo age, afferma che dovrebbe essere impossibile dire, dalla notazione, se Person.agecorrisponde internamente a qualcosa di simile return current_year - self.birth_dateo semplicemente return self.age, dove self.ageè stato definito come un attributo costante. Questo ha senso per me. Tuttavia, continua sostenendo quanto segue:

La documentazione client standard per una classe, conosciuta come la forma abbreviata della classe, sarà ideata in modo da non rivelare se una determinata caratteristica è un attributo o una funzione (nei casi in cui potrebbe essere).

cioè, afferma che anche la documentazione per la classe dovrebbe evitare di specificare se un "getter" esegue o meno un calcolo.

Questo non lo seguo. La documentazione non è l'unico posto in cui sarebbe importante informare gli utenti di questa distinzione? Se dovessi progettare un database pieno di Personoggetti, non sarebbe importante sapere se si Person.agetratta di una chiamata costosa o meno , così potrei decidere se implementare o meno una sorta di cache per esso? Ho frainteso quello che sta dicendo o è solo un esempio particolarmente estremo della filosofia del design OOP?

Non credo che il punto di Meyer sia che non dovresti dire all'utente quando hai un'operazione costosa. Se la tua funzione sta per colpire il database, o fare una richiesta a un server web, e passare diverse ore a calcolare, sarà necessario che lo sappia altro codice.

Ma il programmatore che usa la tua classe non ha bisogno di sapere se hai implementato:

return currentAge;

o:

return getCurrentYear() - yearBorn;

Le caratteristiche prestazionali tra questi due approcci sono così minime che non dovrebbe importare. Il programmatore che usa la tua classe in realtà non dovrebbe preoccuparsi di ciò che hai. Questo è il punto di Meyer.

Ma non è sempre così, ad esempio, supponiamo di avere un metodo di dimensione su un contenitore. Quello potrebbe essere implementato:

return size;

o

return end_pointer - start_pointer;

o potrebbe essere:

count = 0
for(Node * node = firstNode; node; node = node->next)
{
    count++
}
return count

La differenza tra i primi due non dovrebbe davvero importare. Ma l'ultimo potrebbe avere gravi conseguenze sulle prestazioni. Ecco perché lo STL, per esempio, dice che lo .size()è O(1). Non documenta esattamente come viene calcolata la dimensione, ma mi dà le caratteristiche prestazionali.

Quindi : documentare problemi di prestazioni. Non documentare i dettagli di implementazione. Non mi interessa come std :: sort ordina le mie cose, purché lo faccia in modo corretto ed efficiente. Anche la tua classe non dovrebbe documentare come calcola le cose, ma se qualcosa ha un profilo prestazionale inaspettato, documentalo.

Dal punto di vista accademico o dei puristi del CS, naturalmente non è possibile descrivere nella documentazione nulla sugli aspetti interni dell'implementazione di una funzione. Questo perché l'utente di una classe dovrebbe idealmente non fare ipotesi sull'implementazione interna della classe. Se l'implementazione cambia, idealmente nessun utente non se ne accorgerà: la funzione crea un'astrazione e gli interni dovrebbero essere completamente nascosti.

Tuttavia, la maggior parte dei programmi del mondo reale soffre della "Legge delle astrazioni che perdono " di Joel Spolsky , che dice

"Tutte le astrazioni non banali, in una certa misura, perdono."

Ciò significa che è praticamente impossibile creare un'astrazione completa della scatola nera di funzionalità complesse. E un sintomo tipico di questo sono problemi di prestazioni. Quindi, per i programmi del mondo reale, può diventare molto importante quali chiamate sono costose e quali no, e una buona documentazione dovrebbe includere tali informazioni (o dovrebbe indicare dove l'utente di una classe è autorizzato a fare ipotesi sulle prestazioni e dove no ).

Quindi il mio consiglio è: includi le informazioni su potenziali chiamate costose se scrivi documenti per un programma del mondo reale ed escludilo per un programma che stai scrivendo solo per scopi educativi del tuo corso CS, dato che qualsiasi considerazione sulle prestazioni dovrebbe essere mantenuta intenzionalmente fuori portata.

Puoi scrivere se una determinata chiamata è costosa o meno. Meglio, usare una convenzione di denominazione come getAgeper un accesso rapido loadAgeo fetchAgeper ricerche costose. Volete sicuramente informare l'utente se il metodo sta eseguendo IO.

Ogni dettaglio che dai nella documentazione è come un contratto che deve essere onorato dalla classe. Dovrebbe informare su comportamenti importanti. Spesso vedrai un'indicazione di complessità con una grande notazione O. Ma di solito vuoi essere basso e al punto.

Se dovessi progettare un database pieno di oggetti Person, non sarebbe importante sapere se Person.age è una chiamata costosa?

Sì.

Questo è il motivo per cui a volte utilizzo le Find()funzioni per indicare che la chiamata potrebbe richiedere del tempo. Questa è più una convenzione che altro. Il tempo impiegato per la restituzione di una funzione o di un attributo non fa alcuna differenza per il programma (anche se potrebbe essere per l'utente), sebbene tra i programmatori ci si aspetti che, se viene dichiarato come attributo, il costo per chiamarlo dovrebbe essere Basso.

In ogni caso, nel codice stesso dovrebbero esserci informazioni sufficienti per dedurre se qualcosa è una funzione o un attributo, quindi non vedo davvero la necessità di dirlo nella documentazione.

È importante notare che la prima edizione di questo libro è stata scritta nel 1988, nei primi giorni di OOP. Queste persone stavano lavorando con linguaggi più puramente orientati agli oggetti che sono ampiamente utilizzati oggi. Le nostre lingue OO più popolari oggi - C ++, C # e Java - presentano alcune differenze piuttosto significative rispetto al modo in cui funzionavano le prime, più puramente OO.

In un linguaggio come C ++ e Java, è necessario distinguere tra l'accesso a un attributo e una chiamata al metodo. C'è un mondo di differenza tra instance.getter_methode instance.getter_method(). Uno in realtà ottiene il tuo valore e l'altro no.

Quando si lavora con un linguaggio più puramente OO, della persuasione Smalltalk o Ruby (che sembra essere la lingua Eiffel usata in questo libro), diventa un consiglio perfettamente valido. Queste lingue chiameranno implicitamente metodi per te. Non vi è alcuna differenza tra instance.attributee instance.getter_method.

Non vorrei sudare questo punto o prenderlo troppo dogmaticamente. L'intenzione è buona - non vuoi che gli utenti della tua classe si preoccupino dei dettagli di implementazione irrilevanti - ma non si traduce in modo chiaro nella sintassi di molti linguaggi moderni.

Come utente, non è necessario sapere come viene implementato qualcosa.

Se le prestazioni sono un problema, qualcosa deve essere fatto all'interno dell'implementazione della classe, non attorno ad essa. Pertanto, l'azione corretta è quella di correggere l'implementazione della classe o di presentare un bug al manutentore.

Qualsiasi documentazione orientata al programmatore che non è in grado di informare i programmatori sul costo della complessità delle routine / dei metodi è difettosa.

• Stiamo cercando di produrre metodi privi di effetti collaterali.

• Se l'esecuzione di un metodo presenta complessità del tempo di esecuzione e / o complessità della memoria diverse da O(1), in ambienti con limiti di memoria o di tempo, si può considerare che abbiano effetti collaterali .

• Il principio della minima sorpresa viene violato se un metodo fa qualcosa di completamente inaspettato - in questo caso, trascinando la memoria o sprecando il tempo della CPU.

Penso che tu l'abbia capito correttamente, ma penso anche che tu abbia un buon punto. se Person.ageè implementato con un calcolo costoso, penso che mi piacerebbe vederlo anche nella documentazione. Potrebbe fare la differenza tra chiamarlo ripetutamente (se si tratta di un'operazione poco costosa) o chiamarlo una volta e memorizzarne il valore nella cache (se costoso). Non lo so per certo, ma penso che in questo caso Meyer potrebbe essere d'accordo sul fatto che un avviso nella documentazione dovrebbe essere incluso.

Un altro modo per gestirlo potrebbe essere quello di introdurre un nuovo attributo il cui nome implica che potrebbe aver luogo un lungo calcolo (come Person.ageCalculatedFromDB) e quindi Person.agerestituire un valore memorizzato nella cache all'interno della classe, ma questo potrebbe non essere sempre appropriato e sembra complicare eccessivamente cose, secondo me.

La documentazione per le classi orientate agli oggetti comporta spesso un compromesso tra la flessibilità dei gestori della classe e la possibilità di modificarne il design, anziché consentire ai consumatori della classe di sfruttare appieno il proprio potenziale. Se una classe immutabile avrà un numero di proprietà che avrà una certa esatta relazione tra loro (ad esempio la Left, RighteWidthproprietà di un rettangolo allineato alla griglia con coordinate intere), si potrebbe progettare la classe per memorizzare qualsiasi combinazione di due proprietà e calcolare la terza, oppure si potrebbe progettare per memorizzare tutte e tre. Se nulla sull'interfaccia chiarisce quali proprietà sono memorizzate, il programmatore della classe potrebbe essere in grado di cambiare il design nel caso in cui ciò risultasse utile per qualche motivo. Al contrario, se ad esempio due delle proprietà sono esposte come finalcampi e la terza no, le versioni future della classe dovranno sempre utilizzare le stesse due proprietà della "base".

Se le proprietà non hanno una relazione esatta (ad esempio perché sono floato doublepiuttosto che int), potrebbe essere necessario documentare quali proprietà "definiscono" il valore di una classe. Ad esempio, anche se si suppone che il Leftplus Widthsia uguale Right, la matematica in virgola mobile è spesso inesatta. Ad esempio, supponiamo Rectangleche un tipo che usa type Floataccetti Lefte Widthche i parametri del costruttore siano costruiti con Leftdato come 1234567fe Widthcome 1.1f. La migliore floatrappresentazione della somma è 1234568.125 [che può essere visualizzata come 1234568.13]; il prossimo più piccolo floatsarebbe 1234568.0. Se la classe effettivamente memorizza LefteWidth, potrebbe riportare il valore della larghezza così come è stato specificato. Se, tuttavia, il costruttore calcolasse in Rightbase al pass-in Lefte Width, e successivamente calcolato in Widthbase a Lefte Right, segnalerebbe la larghezza 1.25fanziché il pass-in 1.1f.

Con le classi mutabili, le cose possono essere ancora più interessanti, dal momento che una modifica a uno dei valori interconnessi implica una modifica ad almeno un'altra, ma potrebbe non essere sempre chiaro quale. In alcuni casi, può essere meglio per evitare di avere metodi che "set" una singola proprietà in quanto tale, ma invece hanno o metodi per es SetLeftAndWidtho SetLeftAndRight, altrimenti chiaramente quali sono stati specificati e che cambiano (ad esempio MoveRightEdgeToSetWidth, ChangeWidthToSetLeftEdgeo MoveShapeToSetRightEdge) .

A volte può essere utile avere una classe che tenga traccia di quali valori delle proprietà sono stati specificati e quali sono stati calcolati da altri. Ad esempio, una classe "moment in time" potrebbe includere un orario assoluto, un orario locale e un offset del fuso orario. Come con molti di questi tipi, date due informazioni qualsiasi, si può calcolare il terzo. Sapendo qualel'informazione è stata calcolata, tuttavia, a volte può essere importante. Ad esempio, supponiamo che un evento venga registrato come accaduto alle "17:00 UTC, fuso orario -5, ora locale 12:00 pm", e uno in seguito scopre che il fuso orario avrebbe dovuto essere -6. Se si sa che l'UTC è stato registrato da un server, il record deve essere corretto in "18:00 UTC, fuso orario -6, ora locale 12:00 pm"; se qualcuno digita l'ora locale senza orologio, dovrebbe essere "17:00 UTC, fuso orario -6, ora locale 11:00". Senza sapere se l'ora globale o locale dovrebbe essere considerata "più credibile", tuttavia, non è possibile sapere quale correzione applicare. Se, tuttavia, il record tenesse traccia dell'ora specificata, le modifiche al fuso orario potrebbero lasciarlo solo mentre si cambia l'altro.

Tutte queste regole su come nascondere le informazioni nelle classi hanno perfettamente senso sull'ipotesi di dover proteggere da qualcuno tra gli utenti della classe che commetterà l'errore di creare una dipendenza dall'implementazione interna.

Va bene integrare tale protezione, se la classe ha un tale pubblico. Ma quando l'utente scrive una chiamata a una funzione della tua classe, si fidano di te con il loro conto bancario al momento dell'esecuzione.

Ecco il genere di cose che vedo molto:

1. Gli oggetti hanno un bit "modificato" che dice se sono, in un certo senso, obsoleti. Abbastanza semplice, ma poi hanno oggetti subordinati, quindi è semplice lasciare che "modificata" sia una funzione che sommi tutti gli oggetti subordinati. Quindi se ci sono più livelli di oggetti subordinati (a volte condividono lo stesso oggetto più di una volta) semplici "Get" s della proprietà "modificata" possono richiedere una buona frazione del tempo di esecuzione.

2. Quando un oggetto viene in qualche modo modificato, si presume che gli altri oggetti sparsi nel software debbano essere "notificati". Ciò può avvenire su più livelli di struttura dati, finestre, ecc. Scritti da diversi programmatori e talvolta ripetersi in infinite ricorsioni che devono essere protette. Anche se tutti gli autori di quei gestori delle notifiche sono ragionevolmente attenti a non perdere tempo, l'intera interazione composita può finire per usare una frazione non prevista e dolorosamente ampia di tempo di esecuzione, e l'assunto che sia semplicemente "necessario" è fatto beato.

Quindi, mi piace vedere le classi che presentano un'interfaccia pulita e astratta al mondo esterno, ma mi piace avere un'idea di come funzionano, se non altro per capire quale lavoro mi stanno salvando. Ma oltre a ciò, tendo a pensare che "less is more". Le persone sono così innamorate della struttura dei dati che pensano che sia meglio, e quando eseguo l'ottimizzazione delle prestazioni, l'enorme ragione universale per i problemi di prestazioni è l'adesione faticosa alle strutture di dati gonfiate costruite nel modo in cui le persone vengono insegnate.

Quindi vai a capire.

L'aggiunta di dettagli di implementazione come "calcola o meno" o "informazioni sulle prestazioni" rende più difficile mantenere sincronizzati codice e documento .

Esempio:

Se si dispone di un metodo "costoso per le prestazioni", si desidera documentare "costoso" anche per tutte le classi che utilizzano il metodo? cosa succede se si modifica l'implementazione per non essere più costosa. Vuoi aggiornare queste informazioni anche a tutti i consumatori?

Naturalmente è bello che un manutentore del codice ottenga tutte le informazioni importanti dalla documentazione del codice, ma non mi piace la documentazione che afferma qualcosa che non è più valido (non sincronizzato con il codice)

Come la risposta accettata giunge alla conclusione:

Quindi: documentare problemi di prestazioni.

e il codice auto-documentato è considerato migliore della documentazione, ne consegue che il nome del metodo dovrebbe indicare risultati insoliti in termini di prestazioni.

Quindi ancora Person.ageper return current_year - self.birth_datema se il metodo utilizza un ciclo per calcolare l'età (sì):Person.calculateAge()