UML Class Diagram: come descrivere la funzionalità del metodo?

However, I am still unsure how or where I am supposed to describe the functionality that a method of a class offers.

Questa è una preoccupazione valida. Dovrei essere in grado di guardare il tuo diagramma UML e avere una buona idea di cosa facciano i metodi.

In code, I would simply put a docblock above a method in which I describe that method's purpose. Where would I put that information in a UML diagram?

Bene, ecco il tuo problema Stai sbagliando tutto questo.

• Object Constraint Language, either in a note on the class or a separate document. However, I don't think I can express the whole functionality this way

No.

• A note on the class that contains the same verbal description that I would put in a docblock. However, this way I would have a lot of notes in my diagram I guess

No.

• Accompanying diagrams like sequence diagrams or communication diagrams, but that seems pretty verbose

No.

• Use case diagrams/descriptions. Seems also pretty verbose if a single sentence as in a docblock is enough to describe a method's purpose.

No.

So I am wondering: How would I 'translate' a docblock description into UML?

Non lo fai.

UML fa un ottimo lavoro costringendoti a guardare il tuo design dal punto di vista dell'interfaccia che stai offrendo. Stai guardando la tua interfaccia e rendi conto che è confuso, quindi vuoi spiegarlo. No.

UML Class Diagram: How to describe method functionality?

Dai al metodo un buon nome.

Se ciò non è sufficiente, è necessario riprogettarlo. Smetti di farmi dare un'occhiata ai metodi per capire cosa fanno . Se guardo dentro e sono sorpreso da ciò che fa, allora hai problemi che un blocco doc non sta andando a risolvere. Al massimo un blocco doc dovrebbe confermare ciò che sospettavo prima di guardare dentro.

L'unica cosa che dovrei imparare guardando dentro è COME fa quello che fa. Queste informazioni non appartengono comunque al tuo design UML. Questo è un dettaglio di implementazione.

In un diagramma di classe, in genere non mostri la funzionalità di un particolare metodo. Questo non è lo scopo di un diagramma di classe. Hai ragione che puoi utilizzare Object Constraint Language o pseudocode in una nota, ma non penso che ciò avvenga spesso.

Considera la modalità in cui stai utilizzando UML . Se stai utilizzando UML come progetto , vorrai la verbosità di un tipo di diagramma diverso in modo che tu possa specificare chiaramente il comportamento previsto per qualcun altro. Sequenza, attività e diagrammi di comunicazione possono essere tutti utilizzati per rappresentare il flusso attraverso uno o più metodi. Ma se utilizzi UML come schizzo o note , quindi forse non hai bisogno di quel dettaglio in più di un diagramma separato perché la firma del metodo (nome, parametri di input e tipo di ritorno) sono sufficienti per comprendere lo scopo.

However, I am still unsure how or where I am supposed to describe the functionality that a method of a class offers.

In code, I would simply put a docblock above a method in which I describe that method's purpose. Where would I put that information in a UML diagram?

Usa i buoni nomi

UML è un linguaggio di modellazione che è visivo , generalmente più del codice sorgente. Tuttavia, le buone strategie di denominazione si applicano allo stesso modo ai metodi di classe, indipendentemente dalla loro rappresentazione (UML o codice sorgente). Un buon nome cattura il "cosa" di un metodo. Di solito, questo nome si adatta bene al nome della classe. È il principio di strong (alta) coesione .

Se usi un buon nome, non ti serviranno molte spiegazioni! Suggerirei di usare il codice sorgente per commentare cose come autori che hanno modificato il codice, le date, ecc.

Puoi applicare il refactoring ai modelli UML (ad es., i diagrammi di sequenza che generano nuovi diagrammi di classe), proprio come fai con il sorgente. I metodi di ridenominazione e i metodi di estrazione sono un modo per rendere la tua soluzione più comprensibile (e anche più riutilizzabile). Di nuovo, questo va lungo le linee di alta coesione. Attenzione, tuttavia, che come refactoring, i docblock scritti (nel testo) non si aggiornano da soli. È facile che la soluzione diventi incoerente con il tuo docblock.

So I am wondering: How would I 'translate' a docblock description into UML?

Le descrizioni di Docblock sono fondamentalmente commenti . Il modo migliore per scrivere commenti è un argomento controverso nell'ingegneria del software, dal momento che è molto facile che i commenti diventino incoerenti con il codice (o il modello, se si utilizza UML).

I diagrammi di sequenza per un metodo mostreranno il "come" del metodo e sono migliori di qualsiasi docblock perché sono visivi e dovrebbero essere coerenti con la soluzione reale. Alcuni strumenti UML consentono la generazione di diagrammi di sequenza dal codice sorgente (o viceversa), in modo da poter vedere immediatamente come funziona un metodo. Tuttavia, la qualità di questa generazione è soggetta allo strumento e alla complessità del metodo.

Se il tuo metodo sta davvero facendo qualcosa di non scontato, una nota UML sarebbe un buon modo per mostrare quelle cose, proprio come i commenti di linea sono usati in un linguaggio di programmazione. Ecco un esempio del libro Applying UML and patterns di Craig Larman: