Monthly Archives: September 2022

Interpreting Railroad diagrams

16 Friday Sep 2022

Posted by in General, railroad diagrams, Technology

≈ Leave a comment

Tags

, , , ,

Having previously blogged about being a fan of Railroad diagrams (here) as a means to communicate language syntax, I have been asked about some of the ways details should be represented. I’ve looked around and not actually found an easy-to-read for ‘newbies’ guide to reading railroad diagrams. A lot of content either focuses on the generator tools or how the representation compares to BNF (Backus Naur Form) – all very distracting. So, I thought as an advocate, I should help address the gap (the documentation with TabAkins tool does a good job of explaining things, but its focus is on the features provided rather than understanding the notation).

Reading Railroad Diagrams

The following table provides all the information to help you interpret the Railroad Diagrams, and create syntax representations.

  • If you’re only interested in understanding the notation, read just the first two columns.
  • If you want to see examples of how to create the diagram, then the 3rd column will help.

Note: Clicking on the diagrams will result in a bigger version of the image being displayed.

How to Interpret the RailroadRailroad RepresentationCode using tabakins tool
The start and end of an expression are shown with vertical bars.
The expression is read from left to right following a path defined by the line(s).		Diagram(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),
Terminal(' mp3monster '),
Terminal(' blog ')
)
Larger diagrams may need to be read both across and down the page to make it sensibly fit a page like this.Diagram( Stack(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),
Terminal(' mp3monster '),
Terminal(' blog '))
)
We can differentiate between literal values and ‘variables’ by shape. A square shape should denote a variable, and a lozenge represents a literal.
I have to admit to sometimes getting these the wrong way around, but as long as the notation is used consistently in an expression, it isn’t too critical. In this example, we have replaced mp3monster with the name of a variable called domain-name. So if I set the variable domain-name = mp3monster then I’d read the same result.		Diagram( Stack(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),
NonTerminal(' domain-name'),
Terminal(' blog '))
)
We can make parts of an expression optional. This can be seen by following an alternate path around the optional element.
In this case, we’ve made the domain-name optional. Assuming domain-name = mp3monster, we could get either:
– This is a mp3monster blog OR
– This is a blog		Diagram( Stack(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),
Optional(
NonTerminal(' domain-name')),
Terminal(' blog '))
)
We can represent optionality by having the flow split to multiple values. Those values could be either literal values or variables. In this case, we now have several possible names in the blog with the choices being mp3monster, phil-wilkins, cloud-native, or the contents of the variable domain-name. So the expression here could resolve to (assuming domain-name = something-else):
– This is a mp3monster blog OR
– This is a phil-wilkins blog OR
– This is a cloud-native blog OR
– This is a something-else blog
It is typical for the option most likely to be selected to be the value that is directly in line with the choice. Here that would mean the default would be phil-wilkins		Diagram( Stack(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),
Choice(1,
' mp3monster',
' phil-wilkins ',
' cloud-native ',
NonTerminal('domain-name')),
Terminal(' blog '))
)
We can have variations on a choice where we can express the choice as being any of the options (one or more e.g. mp3monster and cloud-native) or all of the choices. These scenarios are differentiated by the additional symbols before and after the choice.
Diagram( Stack(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),
MultipleChoice(1,
'any',' mp3monster',
' phil-wilkins ',
' cloud-native ',
NonTerminal('domain-name')),
Terminal(' blog '))
)
We can represent the looping with the inclusion of an additional literal(s) or variable(s) by having a second line from the right (exit) of a literal or variable and flowing back into the left (entry) of a literal or variable. Then in the loop of the flow below are the variable(s) or literal(s) that go around between each occurrence of the loop. If our variable was a list now i.e. domain-name = [‘ mp3monster’, ‘cloud-native’] then this would resolve to :
This is a mp3monster and cloud-native blog		Diagram( Stack(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),
OneOrMore(
NonTerminal('domain-name'),
[' and '])),
Terminal(' blog ')
)
We can group literals and variables together with a label. These groupings are denoted with a dashed line and usually include some sort of label. In our example, we’ve grouped two literal values together and called that group the blog name.Diagram( Stack(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),),
Group(Sequence(
Terminal(' mp3monster '),
Terminal(' blog ')),
['blog name'])
)

All of these constructs can be combined so you can do things like making choices optional, and iterate over multiple variables and literals.

Tips & Tricks to Consider

TipsRailroad RepresentationCode using tabakins tool
Sometimes the number of options in a choice can get impractically large to show in a Railroad diagram. One way to overcome this is to show the first and last options and an ellipsis.
We can then wrap it with a comment that directs the reader to the complete list of choices.
This way the diagram continues to be readable – the most valuable part of the diagram and easy to locate the specific fine details.		Diagram( Stack(
Terminal(‘This ‘),
Terminal(‘ is ‘),
Terminal(‘ a ‘),
Group(Choice(1,
‘ mp3monster’,
‘ … ‘,
‘ cloud-native ‘), [‘ See Section X for full list’]),
Terminal(‘ blog ‘))
)

Stop polling, Let’s go Streaming the podcast

15 Thursday Sep 2022

Posted by in General, Podcasts

≈ Leave a comment

Tags

, , , ,

I was fortunate enough to be invited to join LogRocket‘s Podcast (PodRocket) to discuss some of the insights and considerations relating to API Streaming that I presented at a reference conference. To hear more go checkout :

If you’d like to see more from the presentation, go here.

CI/CD worker nodes as virtual machines or K8s Containers?

07 Wednesday Sep 2022

Posted by in General

≈ Leave a comment

Tags

, , , , , , , ,

When it comes to CI/CD deployments, something that doesn’t show very often in documentation is the pros and cons of running your worker nodes as containers in a Kubernetes environment or as (virtual) machines in a cloud environment.

Containerized CI/CD
Continue reading →

Decision Matrix aka ‘Stress Test’ as a vehicle to make decisions easier

02 Friday Sep 2022

Posted by in General

≈ 2 Comments

Tags

, , , , , ,

We’ve all encountered decision trees at one time or another as a means to determine an answer based on a set of inputs. The problem with decision trees is that they are binary in nature. The answer is always yes or no.

From http://www.stodolkiewicz.com/2020/04/27/decision-trees-introduction/

But life is not binary. This is often best underlined by the classic joke of asking an architect what the right thing to do is, and you’ll get the answer ‘it depends‘. The art of being an architect is working out what the right trade-offs are when coming to a decision. This is fine, but to know all the factors (or trade-offs) that need to be considered requires a wealth of experience (a rare and expensive asset) or someone capturing these insights in a consumable manner that enables people who will understand how to use imparted wisdom, rather than try to blindly follow binary decisions.

This is where decision Matrices, or as I was introduced to them ‘Stress Tests’ – so called because the matrix is made up of a factor or ‘stressor’ are tested against one or more options. Each slot in the matrix can either be marked as yes/no or scored on the range (for example 1-5) on alignment to meeting the stressor. If you’re doing a product selection then the options are the different products. But equally the options could be an architectural pattern.

This is probably best illustrated. So the following Matrix looks at different programming languages against a range of different stressors. This isn’t a realistic case, but sufficient to help convey the idea. (The assessments in this matrix are not comprehensively researched, so feel free to argue)

JavaPythonRubyC++
Single binary for multiple OS and architectures554 11
Language evolves quickly to provide standardized libraries for common needs5543
Suitable for scripting and application development42541
Readily available skills453333
  1. Ruby has several variants such as JRuby, Ruby with a C core – this has the potential to impact
  2. Use of Shebang or overlaying with Groovy makes Java more usable as a scripting language
  3. Not so commonly taught in educational settings which typically favor Python and Java

As you can see to help use the matrix we can add elaboration notes. To use the matrix we simply determine which stressors are most important or not and then score the different options. So if I wanted to use the matrix to determine which language is most suitable for developing a deployment utility then we know from the use case performance is less critical, portability is important, and skills should outweigh language evolution. Based on that the answer should resolve to Python failing that Java would be good enough.

While our question and its outcome is fairly obvious, in more nuanced situations the stress test gives several benefits:

  • The decision process becomes transparent and easily communicated.
  • The hard work is in developing the stressors and researching the different options in terms of how they fit with stressors.
  • The matrix can be re-used, to help achieve other decisions. What if I was looking at the most suited solution for running data analytics that can maximize GPUs?

Through the use of the stress test we can translate the ‘it depends‘ to a more concrete but rationalized decision.