-
Notifications
You must be signed in to change notification settings - Fork 9
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
Improving "Movie details" example diagram #2
Comments
Thanks for taking the time to have a good look at it. Appreciate that. Yeah the UML specs has a bunch of stuff. That said the diagram is indeed auto-generated with yed, which is the tool I use. I mean the visualization is auto-generated (this is a hierarchic layout), the labels I put by hand. The great thing with yed is that I don't have to think about these things. I just push a button and it draws the graph. So I could for instance generate a graphml file from the Kingly machine definition, and not care about what it will look like. The hierarchic layout, the flowchart layout are generally good options, even if it is never perfect (sometimes it gives weird stuff with some edge crossing) but it is good enough. On another note, a good tool to draw these graph by hand is bpmn.io, complying with the UML specs. It is actually a professional tool used in the industry but I found it painful to draw stuff by hand. The two edges for the same event is to mirror the specs which gives the requirements as separated. I put that as a note on Kingly doc site. It is indeed possible to use a logical OR, but I found it better to mirror the specs. The visualization has multiple competing goals for sure, but one of them is to quickly check against design errors, i.e. discrepancies between the specs and the graph. |
What do you mean by
Other considerations:
In short, no premature optimization till you are pretty sure that there won't be much changes in your specs. That's the most 'agile' way for me. I agree with you on naming. Shorter is better, as long as readability is not sacrificed. On the graph instead of Movie Querying it could be Querying as you suggest. I have one constraint though with Kingly which is that all control state names must be distinct, so I usually add the context back in the name so it can be read in isolation. This is in the name of simplicity: you avoid having to prefix a control state with its parent state to avoid duplicates or disambiguate. I tried prefixing in a previous version, it is beyond annoying. xstate does have a selector system though, a bit like css, but that is something else that has to be learnt, other possibilities of making mistakes and those composed selector names are hard to type (at least properly, you can always just say it is a string but that does not help much). Maybe Rust has a better type system addressing this? The TypeScript version I used back then certainly did not do the job. Generally speaking your comments remind me a lot of best practices for programs. I would argue that the visualization is not a program though, but the (visual) description of a data structure. I optimize that description for reads more than for writes. That said I appreciate that readability is a subjective matter, and it is great to have other people's opinions on the subject, specially the opposite ones. It leads to reconsider some assumptions as I will do now. |
@DrSensor I have been reviewing many many tools for drawing state machines, including paid tools, and I came to the conclusion that in the short term, using yed is still the best option. It is the most user friendly and productive by far, have terrific automatic layouts that are enlightening, and allow for plenty of customization of styling. Also it is free to use. Yed may support the type of factoring that you were recommending in the discussion above. I could do this by assigning meaning to shapes (like a diamond for conditional event routing etc.). After playing with a few alternaive designs and measuring the productivity, learning cost and flexibility, I chose what seems to me to be the most agile route.
To those general principles, I added a few conveniences:
I rejected the following conveniences:
I am putting the final touches to the integration with yed, the compiler and the final API, so I may eventually reach a 1.0 and make some noise. More details will be available in the (upcoming) documentation. Thanks for the advices and comments that you contributed, that is very much appreciated. |
My review for this diagram (it might be a bit harsh 😅)
https://brucou.github.io/documentation/graphs/movie-search/TMDB-movie-query-and-detail.html
Review
Since it's not auto-generated diagram, there is 2 tips which I use as a basis:
Starting from no.1
![Screenshot_20190722_112729](https://user-images.githubusercontent.com/4953069/61606252-9571f200-ac73-11e9-8267-4a27e6b2ce46.png)
![Screenshot_20190722_115559](https://user-images.githubusercontent.com/4953069/61607149-9147d380-ac77-11e9-8d3c-7af30813b9d6.png)
This can be avoided if you use pseudo state in several area. Also this happen because you use 2 edge on the same event
![Screenshot_20190722_114427-2](https://user-images.githubusercontent.com/4953069/61606882-893b6400-ac76-11e9-8ca8-8b554a1549f4.png)
You can rewrite it something like this
It also weird that there is 2 auto transition
![Screenshot_20190722_115307](https://user-images.githubusercontent.com/4953069/61607050-28f8f200-ac77-11e9-91c2-135e2e2ef556.png)
Just make it one edges and write it as
['/' or '/:query'] / ...
Again, make this edges one-to-many or many-to-one using pseudo-state
Regarding to naming, don't name it to long. For example
display ___ screen
just name itshow loading
orerror screen
. As a side note, keep in mind to target accessibility user too.And the state name too. The context of the child state can be inferred from the parent state. For example:
![Screenshot_20190722_120813](https://user-images.githubusercontent.com/4953069/61607512-43cc6600-ac79-11e9-8710-e0745c6e4978.png)
Just name the state querying, selection, and error.
Lastly, there is a trick where you can separate the details in another block. It's a bit cumbersome for me to draw 😂. So, see that in OMG UML spec figure 14.12-14 page 325-326.
The text was updated successfully, but these errors were encountered: