-
Notifications
You must be signed in to change notification settings - Fork 1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Blog post on UML and the Strategy Design Pattern #52
base: main
Are you sure you want to change the base?
Conversation
…Strategy Design Pattern followed by a practical example from option pricing. In particular, we: - Introduce UML and its role in software architecture - Detail the Strategy Pattern and its components (Context, Strategy Interface, ConcreteStrategy) - Include a practical example of pricing European options using the Black-Scholes-Merton equation - Integrate relevant mathematical expressions and explanations
for more information, see https://pre-commit.ci
- Fix trailing whitespace issues
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've given a first pass to the post. It looks very good, but it will require several revisions until it is polished enough for publication.
I've left a few comments below but the main points are:
- You need to add some links between sections to facilitate the reader to move naturally form one to another. As it is now, you seem to jump from one topic to another with no clear reason.
- I'm a bit unsure about including equations. They are not complicated and I think it is nice to make it clear what you are solving, but they can be very obscure to someone not in the financial world. Maybe, to facilitate people going through them, explain what they are about, what they are useful for, etc.
European Call
andEuropean Put
don't say much. - Your premise for using UML diagram is to get to a code that is not overengineer but your code is very overengineer. You are using classes where you only need simple functions, which is one of the main criticisms of OOB: not everything needs to be a class! I've suggested a change that will improve that part, but obviously the UML diagrams will need updating accordingly. Probably things can be simplified further, but let's leave it here and see what others have to say.
docs/posts/design_patterns.md
Outdated
Over-engineering at the prototyping or proof-of-concept stage can be counterproductive. However, as systems mature, this approach can lead to technical debt, | ||
resulting in code that is difficult, if not impossible, to maintain. | ||
|
||
In the following, we first describe UML diagrams and how they are used to plan and visualise software architecture before coding itself. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This paragraph here comes a bit out of the blue after the nice introduction above. I would suggest something along the lines of:
In this blog post we will... (some indication of the overall purpose of the post, linking the above introduction to what is coming next). We first start describing UML diagrams...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agree. Describing how this blog post will address the issues identified in the good introduction above would make the contents and goal of the post more clear. Even if it's obvious to you, it's a reassurance for the reader that they are not just being clickbaited.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It is the least of my intention to deliver click-bait. I have a few concepts to explain here:
- The design patterns and its purpose
- How it can be applied to a concrete example (here: option pricing from finance which essentially is pricing an insurance contract given uncertainty of future evolution of an underlying asset (and hence it is called a "derivative"))
- Incidentally, this forces me to also explain the concept of said derivatives as otherwise it pops out of nowhere for readers unfamiliar with the topic.
Hence, it is not that easy to cater for all interests in the introduction.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I expanded the introduction providing an overview of what the blog post explains. Hopefully, this provides a better overview and makes things clearer.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice to see info on UML and API design 👍
I've added a few points and suggestions. One other thing I note is the title: I feel this content is just as applicable to software developers in other computational fields. Maybe emphasise in the title that the content is more about API design using UML, and (with less emphasis) using a computational finance problem as an example.
docs/posts/design_patterns.md
Outdated
Over-engineering at the prototyping or proof-of-concept stage can be counterproductive. However, as systems mature, this approach can lead to technical debt, | ||
resulting in code that is difficult, if not impossible, to maintain. | ||
|
||
In the following, we first describe UML diagrams and how they are used to plan and visualise software architecture before coding itself. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agree. Describing how this blog post will address the issues identified in the good introduction above would make the contents and goal of the post more clear. Even if it's obvious to you, it's a reassurance for the reader that they are not just being clickbaited.
docs/posts/design_patterns.md
Outdated
*The rendered result should look similar to the above figure.* | ||
|
||
We can now use this our blueprint and engineer software that implements the abstract pattern. | ||
As an example we pick pricing a European call and put option using the `Black-Scholes-Merton` equation, which is |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd hazard a guess that 80% of the audience doesn't know what, or the significance of, any of these things. You may need to spoon feed people a bit here. Briefly why use/what is a European call, the Black-Scholes-Merton equation. Some people might not even know what a PDE is.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I did address this point in my latest commit.
Hello team, thanks for the feedback. I certainly can expand on the background and elaborate more on the the mathematical framework. I am aware on can borrow the ideas from "Design Patterns" and code them in a functional approach rather than an OOP one. I am not sure whether there is a silver bullet here. The main issue of the OOP approach is, that all variables feeding into the equation can be functions of multiple parameters, particularly, the can be time-dependent. I thought an OOP approach might make it easier to inherit from base classes for such an expansion, but of course, this would necessitate multiple inheritance making things nested. I am on RSECon this week, so will not be able to contribute this week. |
I totally understand why you are using OOP, but in the example you use, it just results in the opposite idea you are trying to communicate, how to not over engineer your code. There might be other cases where that is the right approach, but I don't think that is the answer in this one. There's no benefit on using classes in this case. I'd suggest you either come up with an example where using classes is indeed the best approach (eg. if there's a state that needs to be pre-calculated or setup, and then used when needed) or modify your code the way I suggested and re-write the text to match the example. On the background, I think that's a must. Otherwise, only people with some background in finance will understand what's going on. Maybe have a crack at Jame's and my comments and then ask the rest of the reviewers to have a look to the revised version, so we can iteratively improve the blog post. |
that is priced in this tutorial.
I did work on improving the description of the background as to not loose readers unfamiliar with the terms straight away. Regarding OOP vs. functional. I do not have to keep track of the state of the object, but rather to compute a parameter based on inputs (the inputs are mapped to an output via an algebraic manipulation). So indeed the functional approach is the more direct approach here. |
restructured introduction that aims at being more explanatory and clearer on what the blog post deals with. This sets and simultaneously limits expectations and provides the reader with a clear overview.
for more information, see https://pre-commit.ci
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The finance related background and the link between the introduction and the UML diagrams is now much better - and indeed pretty interesting!
However, all the UML diagrams still use the class-based approach which, I think we agreed, is not the right call. Maybe you're already on it, but just a reminder.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I tried running this locally and got:
ERROR - Config value 'plugins': The "plantuml_markdown" plugin is not installed
You will need to add this package to the dependencies (with poetry add
) and make sure it works
Indeed, I am working on the UML diagrams. |
This is a tricky bit: I had a discussion a while back ago with @alexdewar I create the diagrams in a Jupyter notebook like so: This, unfortunately, is not supported using our RSEBlog repository. |
I suggest you switch to using Mermaid, which has full support for class diagrams (maybe not full featured UML ones, although I'm not sure of the difference) and do work with MkDocs. As it is not an extra dependency, but some sort of markdown extension, there should be no issues with poetry. It is even rendered in GitHub directly. We have use it in QwikApp:
|
Morning @dalonsoa, I struggle making my .md file pass markdownlint.
throws the indicated error, while a test link, say, works just fine. Not sure what the issue is caused by. I tried to run |
I have heard of Mermaid. Let me please first make my .md file pass the pre-commit hooks, so people can provide feedback on the text itself before taking a look at yet another tool. |
Some webpages just don't let CI systems to check them easily. The simplest solution is jut to skip checking that link. Check this: RSEBlog/docs/posts/20240722_pydata_london_2024.md Lines 31 to 33 in 43789a7
|
…ged UML diagrams and Oython code accordingly. - Expanded the overall text. - Included a section on the put-call parity to test the fair pricing - Increased the number of references
`.spellcheck.yml`
plantuml | ||
startuml | ||
enduml | ||
labeled |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is "labelled" in UK English. So I'd fix the text rather than ignoring the word.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
mea culpa.
Modeling | ||
Rumbaugh | ||
nd | ||
se |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can we set the spellchecker to ignore two-letter words or something? Does anyone know? Having all these tiny non-words in the dictionary seems really ugly 😬
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I am are of this. .wordlist.txt
has not been a beauty before my post and it will be ever lesser so after.
I am happy for suggestions of other team members to modify spellchecker to resolve this.
I cannot trigger spellchecker locally to verify it runs error-free, and it got somewhat of a pain to make local changes to the .spellcheck.yml
file and pushing them to the repo to trigger the CI pipeline only to experience it fails after 8 to 12 seconds and repeating the loop.
In princliple one should be able to run spellchecker locally like so
pip install pyspelling
pyspelling -c .spellcheck.yml
Also, in an experiment, I appended the following
ignore_patterns:
- '```[a-zA-Z]+\n[\s\S]*?\n```' # Ignore code blocks
- '## References\n(?:- .*\n)*' # Ignore References section
to
.spellcheck.yml`
in order to test whether fenced code-blocks are protected from spellchecker doing its work on them, but to no avail. If someone wants to take a look at that, I think, it should be a separate issue.
Also, I managed to protect the References
section from spellchecker using
References go here
which works well.
docs/posts/design_patterns.md
Outdated
|
||
## References | ||
|
||
<!-- spell-check-ignore --> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If this works, then we can remove "Modeling" from .wordlist.txt
, right?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, that should work. As with C++, I now have code that "compiles", and I now can work on make it more beautiful. But honestly, spellchecker has been a pain and to make it "behave" has been tricky.
As for the Latin phrase "per se", there is not much I can do about it. I do not use them that regularly, although they come across in economic language quite regularly, e.g. "ex-post [comparison]", "cum-ex [date]" , "ceteris paribus", and frankly e.g. and etc. are Latin words as well.
I will remove "Modeling" from the wordlist. I cite the book as a reference. As it is by an American author, the title is with a single l rather a double l.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I know it's correct -- we don't want to be changing the spelling of a title. I just meant that the <!-- spell-check-ignore -->
bit should mean that it isn't flagged.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Re the Latin words (hah -- re is another), I wasn't asking you to change your text! I was just wondering if we could fix the spellchecker configuration for some of the things that don't look like words (e.g. "nd" which I guess is part of "2nd" or something).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I also changed Unified Modeling Language
to Unified Modelling Language
to comply
with the orthography of British English.
docs/posts/design_patterns.md
Outdated
![Definition of the Strategy Pattern](images/design_patterns/def_strategy_pattern.png) | ||
<!-- markdownlint-disable-next-line MD036 --> | ||
*The rendered result should look similar to the above figure.* |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For figure captions, you can do this:
![My figure caption.](path/to/image.png)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I follow your suggestion for the syntax, but am not able to break the caption like this
![This is the first line of the caption.<br>This should be the second line of the caption](path/to/image.png)
Also, see here
for an explanation of the same issue.
Moreover, our markdown application does not support re-shaping images to fit them to the page, see here
Am thankful for suggestions.
Moreover, I reformatted the references sections as well as in-text references. Also, I slightly refined the text for fluency and improved some explanations.
Disappointingly, my clickable references are not accepted by markdown. [Gemma et al. (1994)]
When pushing to the repo, I am thrown the following error:
|
…original implementation renders beautifully and without errors on my local machine, but the pre-commit hooks complain.
…y blog post is in the References section and I thought to disable spellcheck like so <!-- spell-check-ignore --> ... <!-- end-spell-check-ignore --> will make it pass, but as it stands it does not.
Forgive me @alexdewar for hacking Also, I am not quite happy the |
My RSE blog post makes a contribution towards explaining UML and the Strategy Design Pattern followed by a practical example from option pricing.
In particular, we:
Closes #13, #22.