Netrunner: Card macros rename

[Saintis]

An issue to discuss about a rename of the card macros currently named req, effect and msg.

Some background:

• All macros expand to a 5-fn wrapper used as a base building block in the game enginer
• effect adds in state and side function parameters to all highest level blocks inside the macro
• msg additionally wraps the contents of the macro in a str function so it generates a string return
• The use of req and effect is often a steep learning curve for new contributors

This issue proposes that the macros req and effect are renamed to more clearly describe what they are -- which is a function definition wrapper that creates a core game-engine 5 argument function.

It has also been suggested that the renamed macros have the same length, to make it easier to change between then without the need for reformatting.

Suggested names:

• req: req-fn, game-fn, nr-fn, jinteki-fn ...
• effect: inject-state ...

More name suggestions very welcome!

[danhut]

I am not sure a short name can really encapsulate what is going on. I feel this is just a familiarity thing with new people on the team - Macros are alien... For example they don't only wrap but provide bindings to functions too.

I don't really mind what we call them - but maybe we should review the wiki too. And of course we have the when-completed macro and continue-ability macros. They have names that mean something but not sure I'd like (req) to explode into (when-called-wrap) or something...

It might make sense to standardise the function bindings in req, msg, and effect if we are actually doing something here?

[jwarwick]

In terms of confusion, having req/:req and effect/:effect when they no longer are designed to work together is a big issue. Just breaking that implied linkage would be a great change.

[NoahTheDuke]

Let me throw my vote behind fully removing effect and just sticking with req, renamed to whatever makes it meaningful.

[danhut]

I strongly want to keep the effect macro. I am not keen on inserted hundreds of boiler plate state side in every form nested in an effect today. Renaming is ok.

I believe the issue here is familiarity with the code base and Clojure itself. I am really excited we have so many new people on the project - but the confusion will pass very quickly.

I do think we need to figure out a better wait-completed as that is tough. I did discuss with Neal a bit... trying to goad him into it ;)

[presheaf]

FWIW, as a new person, I did find req/effect confusing for a while, but it passed. I would be in favour of name changes - req in particular seems very confusing - but I think a wiki update would be more helpful than a merge of the two.

[jwarwick]

How about effect -> with-state? I do think we should keep both req and effect as well.

[Saintis]

One nice thing about req is that it's short. Maybe g-fn and s-fn where the difference is explained in the wiki / macro-comments. g-fn being short for game-function and s-fn being short for game-function-with-state

[danhut]

Rename effect to FN-2187? The post compile name

[presheaf]

I quite like the name '5-function' for the functions used by Jinteki. IIRC that's illegal as a Clojure name, but I would not mind five-fn as a name for req.

[Saintis]

The issue with five-fn is that it relies on the amount of parameters we need staying at 5. When await stuff was added the former 4-functions were upgraded to 5-functions. I'm not sure that will not happen again.

[NoahTheDuke]

Still thinking about this, tbh.

[NoahTheDuke]

Having thought about it for the last 1.5 years, I don't think they need to be changed.