Why does the reader want to implement the state pattern? #4

New Issue

jordan · 2025-09-03T00:53:56-07:00

jordan commented

2025-09-03 00:53:56 -07:00

On line 55 of the README you introduce the impetus for using the state pattern by considering what a 100 state state machine would look like in code. This is a good example that shows why a switch-case implementation of a state machine sucks (and I think you should refer to the "state machine" as a switch-case to make this clear). What this doesn't do is give the reader a good reason to do different. You claim that the state pattern has better flexibility between states, but why does it have this property? It's not clear from your introduction and I think it needs to be clear immediately to keep the reader engaged - trawling through a code example without some reason to trust the author's claims isn't something that most readers will want to do. (I certainly know that I don't really engage with articles that do this to me.)

What I would like to see to address this is a generic picture of the state pattern and to compare how adding a state to the machine looks like for the state pattern and the switch-case. This should provide impetus to implement it, giving your readers a reason to read and play with the specific code that you've written. It's also a good oppurtunity to highlight the generic operation of the pattern, which seems to be quite the omission from an article discussing the pattern.

It may be good to consider who exactly the target audience is too when writing the generic picture. You've made some assumptions about the knowledge of the reader - familiarity with C and state machines, familiarity with switch-cases getting unweildy. Perhaps it would be good to strip those back a little. Not necessarily the knowledge of C and state machines, but perhaps a good example of how switch-case stacks get unweildy, especially in comparison with the state pattern.

On line 55 of the README you introduce the impetus for using the state pattern by considering what a 100 state state machine would look like in code. This is a good example that shows why a switch-case implementation of a state machine sucks (and I think you should refer to the "state machine" as a switch-case to make this clear). What this doesn't do is give the reader a good reason to do different. You claim that the state pattern has better flexibility between states, but why does it have this property? It's not clear from your introduction and I think it needs to be clear immediately to keep the reader engaged - trawling through a code example without some reason to trust the author's claims isn't something that most readers will want to do. (I certainly know that I don't really engage with articles that do this to me.) What I would like to see to address this is a generic picture of the state pattern and to compare how adding a state to the machine looks like for the state pattern and the switch-case. This should provide impetus to implement it, giving your readers a reason to read and play with the specific code that you've written. It's also a good oppurtunity to highlight the generic operation of the pattern, which seems to be quite the omission from an article discussing the pattern. It may be good to consider who exactly the target audience is too when writing the generic picture. You've made some assumptions about the knowledge of the reader - familiarity with C and state machines, familiarity with switch-cases getting unweildy. Perhaps it would be good to strip those back a little. Not necessarily the knowledge of C and state machines, but perhaps a good example of how switch-case stacks get unweildy, especially in comparison with the state pattern.

jordan referenced this issue

2025-09-03 00:56:37 -07:00

Wording suggestions #5

sirlilpanda added reference making-readme-more-tutorial-like

2025-09-06 20:46:41 -07:00

sirlilpanda referenced this issue

2025-09-06 21:12:12 -07:00

making-readme-more-tutorial-like #6

Sign in to join this conversation.