Zen

[emil14]

This discussion is a heap for everything "conceptual" or "philosophical" about the Nevalang. Everything that feels like a "go proverbs" or "zen of python" must go here. Perhaps later we will structure these thoughts better. This is the place for both the language itself philosophy and heuristics that language users should use.

[emil14]

Pass on

Pass on the data that you take, not only result, so the user of your component can reuse that value without hustle with connections.

Exception for this rule is sig inport. E.g. component that takes sig and returns some real data should not return sig because real data could act as a signal.

[emil14]

Strive for strong invariant

Let's design a structure that represent two possible states: message is full and user should read it and message is empty and user should not do so:

Bad

v = {
ok: bool // if true, then message is not empty
msg: str // not empty if ok is true
}

It's bad because it's possible to have ok==true with msg!='' state that broke invariant.

Also bad

v = {
 msg: str?
}

It's possible to have msg!=nil with msg=='' which also broke invariant.

Good

v = str // empty or not empty

There's just 2 possible states: msg=='' and msg!=''. Both states are implements invariant.

---

Sometimes it's impossible to create structures with unbreakable invariant but it's also possible to find structure with the minimum invalid states. The lesser possible states you have the stronger invariant you get. The goal is to make compiler do as much work as possible so the user of your API can think about more important things

[emil14]

To batch or not to batch

when to use structures instead or separate (out?)ports

TODO

[emil14]

Relax the requirements, enrich the output

Don't be specific at what you accept, but be specific at what you give.

The special case for that is a sig interface. There's a convention that any component that have a sig inport should use type parameter without constraints to allow any type be used as a signal.

TODO think about "return" types examples (and about whether it's a really good rule of thumb)

as an inspiration see Go's "take interfaces, return structs"

[emil14]

Avoid if-else

That stuff looks scary in FBP

TODO

[emil14]

Prefer multiple nodes to not ports

Design the component's API in a way that it should be used on a single "pulse" of data instead of adding an array port in order to allow componentn operate on multiple "pulses"

(Not sure about this one. Array ports actually could be more general-universal. And what about sub-streams?)

[emil14]

Avoid duplicating context in naming

• e.g errRecField instead of errBadRecField for error

TODO create separate naming policy?

[emil14]

any is for anything

If you use any type make sure your intention is "I accept literally anything and it's undesirable to use type-parameters". First means there's no expectations about data-type - it simply doesn't matter. Second means either there's no way to handle the situation with generics either it makes stuff more complicated without bringing benefits.

Example of a good cases for any are:

1. start inport of a main component - it's was possible to use type-parameter but not only it forces us to write a bit more code but it's also doesn't give as anything. Actually it conceptually incorrect - type-parameter means there's possible situations that are different from each other. It's not the case of start port. There's only one place where it's used in one possible way - runtime uses it to kick the program execution by sending an empty message.
2. sigs inport of a flow.Trigger component - generics (non-variadic) cannot express heterogeneous array-inport so we simply have to use any. On the other hand it's completely safe because Trigger has no expectations about what data-type comes to sigs inport. It simply have no interest in that because data is used as just signals

[emil14]

Simple API First

This one first of all must be applied to standard library but it could work well for custom packages as well

Designing the API make sure you cover the most popular use-cases by the simplest API. E.g. having http package is more important than tcp because most of the web application doesn't use tcp directly. This is an example for a language that is used more for a web-development in less for system programming perhaps but that is just an example. Similar if you can cover cases like "create file", "read file" - do that. And only then cover (if necessary) cases like "connect to a unix socket" or something lower level.

Simple API here probably also means "less parameters". It's always important of course to remember that API could easily be too simple and bad because of that. Because it doesn't cover important cases

[emil14]

Left a backdoor

https://youtu.be/xcZ5yq_gG-4?t=777

This is a story about Haskell and Clojure. Haskell's HTTP library that wraps C's curl wasn't complete by wrapping everything. So instead of leaving a backdoor to bypass types and just pass strings author of a library just expose a limited API. That lead to a developers just cmd curl from Haskell binary without type-safety at all. Missing option BTW was SSL cert. That ofc could be fixed by now but the thing is philosophy of "making things RIGHT in the first place" and "not leaving the backdoors".

For a language like Nevaland that wraps Go this could also be an important thing. Even though Go's stdlib is more or less well typed. And the thing with Nevaland could be more about "How do I wrap this?" instead of "How do I wrap everything I could and somehow expose everything else"? It's not clear how to actually expose stuff in a backdoor way cuz paradigms are way too different. Anyway if that's possible for Haskell or Clojure that must be somehow possible for Nevaland.

This could be a part of a more general "be practical first" approach. Like the science and architecture and clean code and patterns and style and stuff are all cool but those are just instruments to make things work (and maintainable, yes). But those are just instruments. The goal they serve is to make language practical.

[emil14]

Principle of Least Astonishment

A component of a system should behave in a way that most users will expect it to behave.

(This one is not created by me and is just common sense from the internet. Not sure if, thus, must be included)

[emil14]

Rule of 7

https://publish.obsidian.md/programmingsimplicity/2023-04-03-Rule-of-7

No node in a layer has more than 7±2 items in it.

[emil14]

Prefer custom errors to multiple outports

Have one err outport that could send several IError exported values instead of having several errN outports. This way user of your component doesn't have to handle all of them if he doesn't want to. Also you gonna have to add new outport each time new error type added which can break the parent component

[emil14]

Multiple instances is better than spaghetti

Good code is the code that is easy to understand by looking at it. If your code looks complicated as a visual schema then it can be improved. One of the possible ways to improve it is to make use of several instances of the same component. Even thought you can actually use one. General rule is that the more connections coming from different places you have that are point to single inport, the more spaghetti-like your component looks.

Example is "a+b" program - it could use only one println instance but it does use 3. As a bonus you can easely customize each one of them e.g. by adding different prefix to printed messages.

(Also could be better for mock configuration?)

---

TODO "won't exit because printlns won't exit" this is a problem