I added my comments to the guidelines (only).

[Ormek]

My intend was to leave your text untouched, but I fixed 1 or 2 typos. I used quote markup for my stuff.

I still intend to add comments to the full essay, but this is all I managed today.
This should not be merged into main.

[Mauitron]

You bring up some very interesting points that warrant reflection. Give me some time to contemplate some of them before giving you an answer. I have a job interview tomorrow, so you can expect me to craft an answer after that.

[Mauitron]

I have a few questions so i can get a clearer picture not only of the problems
you might have brought to light, but also the perspective we are both viewing
it from. If there are any questions i will answer them aswell.

On Flow-Based Organization
Could you give an example of when artificial bounderies are necessery to
achieve a goal? It is not that i am completely disagreeing with you, it is more
the use of the word 'often'. I can only come up with a few reasons as to when
they would help, and half of them are due to time or scope of the project
rather than the code itself.

On Natural Bounderies
You bring up a really good point. The main problem with The River at this point
in time is it being new. It is not tested enough so we don't have enough
datapoints to assess the practical validity of some of the reasoned guidlines.
I do think the argument holds merit logically though, that is why i think it is
likely to work. The idea is to move away from the idea of shared cross-cutting
and focus on having the input or output of a function feed the required data to
whatever needs it. If it be populating a database or authenticate a password or
id. does that make sense?

On Flow of a Feature
Yes, at the end of the day this should be seen as a living document that has a
high probability to change when data is collected. I am sure things will be
modified or added in the future. to what extent i am unsure.

On Readability and Visitor Pattern
I must admit, this made me laugh. I can relate to this a lot. I have heard many
times how self explanitory an abstraction is, and suprise that i am confused.
The problem is the assumption of shared knowlage. it might be that, as you say,
it improve readability of the code for the tribe that created it, but it is one
of the reasons why complexity compounds over time. My asserstion would be that
understanding diverge as codebases and teams grow.

On Reuse
The thing the river tries to eliminate is global errors or bugs. if a check
exist in 99 distinct features, the bug must be very rare. I would at that point
argu that, firstly, it could be likely that the bug is only an issue in one of
the features, and secondly, it happens so rarely that time to fix all the rest
of 99 bugs is likely something that does not need to be hurried.

On Error Handeling
You highlight something very important. I am primarily a Rust developer which
makes me think about error handeling as something explicit. That being said, i
think the mental picture would me more that a river creates tributaries that
feed the computed data to its destination. If it feeds it into another river,
that river would most likely be the main river of the program. But there is
absolutely something that needs to be looked at more carefully.

On the Last Two Points
Do you mean how to design flows to contain and isolate failiurs and making
error states and recovery paths has not been shown/discussed in the essay well
enough? If so, this is a very good point that needs work, thank you! The same
is true for testing i think.

On Allowing and Dealing with Cross-Cutting Locally
In what way do you se this hiding the flow? si am thinking that if you have
logging and security within a linear function, those parts would output the
relevant data directly to where it is needed. avoiding moving data around. The
flow will be perserved because in the function, after you have written you
login info, there will be a bit of code that queries the database to see if it
should be accepted. Does that make sense?

On Following Idioms
I am unsure if I agree with you on this point. You are completely right at any
descrete point in time, but if we take the codebase and look at how it evolves
and gets interacted with through time, do you still think it holds true?

On Constant Complexity Scaling
The idea is that you maintain constant complexity by isolating the complexity
within functions. after a function has been called, it should not need any
other part of the system (hopefully) to deliver the feature it is designed for.
It is important to add that there might be requests for information and/or
manipulations to the database or state, but these, i guess, could be seen more
as lakes/oceans than rivers. They are the parts of the program where rivers
start from, or end at. Do i make sense?

On Proposals
I like your first and third suggestion better than my wording. i will be adding
it. On the other suggestion, on times when it might be necessery: I can see
management reasons as to why they are needed, they could save time that really
needs to be saved, but the cost of using them needs to be carefully weighed as
it compromisses the maintainability of the codebase, which could cost time in
perpituity.

[Ormek]

I added my reply to your comments whithout adding your comments into the text.

Feedback on your reply which I cannot relate to a text location:

On Natural Bounderies.

If it be populating a database or authenticate a password or
id. does that make sense?

Yes, it does make sene.

On Proposals

On the other suggestion, on times when it might be necessery:

I do not know, what you are refering to.

[Ormek]

Examples are requirements like

• test-ability (might require dependency injection to get a mock where it is required.
• Extensability (Others should be able to extend/adapt the flow at runtime)
• Consistency across flows (10 flows should behave similar)

[Ormek]

I believe your reply on this revers to the River-Guidelines yourself and that my comment means that is it not yet complete and should be extended.

My comment addresses something else. The whole "The River" approach assumes a certain main principle of structure. If I draw the program it will always be a flow-chart. My experience differs. In some applications the flow-chart is a good choice and the The-River is a good principle. It then makes sense to follow your guidelines.

But on other occasions other models are better suited to solve the problem. I have yet to elaborate on that and what other structures I mean.

[Ormek]

I accept your reply.

But, take a change in requirement. The resolution of the screen in use will change and those flows do contain actual pixel numbers (which could have been avoided in the first place, but have not). One flow contains: First column (100px) second column (150px) third column (remaining). When 500 pixels were available this is just fine. Now 1000 pixels are available. and I have to double those numbers.
Other flows handled the usage of the availble screen estate in their own independant way.

Contra Flow: How lovely it would have been if they all used a single shared parameterized screen, so I only had to change that one screen.

Pro Flow: How aweful it would have been if I had only a single shared parameterized screen to handle the requirements of 100 different flows. No one will understand the resulting parameters and any change to the screen might break many flows.

I had to deal with such a change for the Porsche Workshoptester.

[Ormek]

Do you mean how to design flows to contain and isolate failiurs and making
error states and recovery paths has not been shown/discussed in the essay well
enough?

yes

[Ormek]

What I mean: The flow in one of your examples is:

    // Parse the request
    // Validate the parameters
    // Query the database
    // Update the database
    // Construct the response

If you add logging, assertions, more checks for security and monitoring additions all this cross cutting concers will clutter up the function and hide the flow. I might not see the actual parsing in the code, because most of the code after the // Parse the request will no longer try to parse the request, but handle those other concerns.

[Ormek]

I think you did not understand my comment. Or I did not understand your reply. Let me try to explain again.

To make things work I have to do C before A before B. If I understand the flow-principle I will have multiple functions which read:

r=C():
if A(r) == failure {
   handleError();
B();

Maybe even with some flow specific stuff inbetween.
How do I ensure across a team or across myself over time (future-me might no longer know what current-me knows) that we always do C before A before B?

I could introduce a functional abstraction: A function that does the above, which I call in every flow. Problem solved.

But I have broken other flow-principles. The error handler is now further away from the context that it aims to report. I no longer have the freedom to move flow specific stuff inbetween those calls to A or B.

If it is already a well known fact to everyone on the team that of course you have to C(); A(); B(); then I might just live with the risk and call that an idiom that I might even put in some documentation or specific coding guideline somewhere.

[Ormek]

it should not need any
other part of the system (hopefully) to deliver the feature it is designed for.

What would I see in a function which does need other parts of the system?

I find it hard to distinguish good from bad functions by that criteria.