Let's talk about the _system suffix in #[system]
- Lingua principale
- Rust
- Stelle
- 1.7k
- Fork
- 140
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Descrizione
This issue is to discuss the problematic nature of relying on compile-time generated code that's user-facing insofar as they are required to invoke that code to use Legion for the most basic of purposes for which it was designed - i.e. something as natural as creating a system.
Please see the problem on the image below.

The solution to this problem is:
> The #[system] macro will create a system and append _system to the function. So instead of referencing your fn, you want to reference the actual system.
I'm looking for clarification, motivation and hopefully justifiable reasoning behind this decision to require users to know about a magic function name, that is, the `_system` suffix onto their declared function name.
This magic symbol makes it impossible for users to surmise how to use Legion without resorting to online documentation or code examples - this is a big red flag that marks a poor design decision. If a core part of the API is based on underhanded knowledge (however thoroughly documented that knowledge may be externally to the code), you're creating a knowledge barrier that new users can't get past on their own. This creates a demotivating atmosphere and limits API discoverability and ease-of-use, as the user will hit an unsolvable barrier literally within minutes of starting to use Legion for which they will have to resort to online help.
If users cannot possibly use an API without requiring online documentation or code examples, that's a poorly designed API. It may be difficult to progress without these aids but it certainly should not be impossible by intentional design. I'm raising my concerns here because this, to me, is a very large red flag that Legion will - however slowly and gradually - move in that direction. It only takes so many instances of "not a big deal" for things to add up to something larger, and this should be nipped in the bud before it takes root.
If you require two named user-facing symbols for every system, make the user declare both names. It will be immediately obvious to the user that the second name exists _and_ serves a purpose, and they will learn to use it or at the very least look it up with intention. This can easily be done in the `#[system]` macro, for example. If the counter-argument to this, as one person suggested, is to avoid boilerplate code then I dare say compile a list of pros/cons and see which comes out worse (and do add a splash of foresight to that list).
Brief list of problem factors with generated `_system` suffix off the top of my head to summarize:
- User is unaware of new (or mutated) symbol name (poor API design)
- User already has a symbol of that name in their code base (confused compiler errors, rename system to less appropriate name vs. refactor existing code)
- User declares their systems with `_system` suffix and now gets generated `visual_system_system`
- Developer (same or new) down the line is required (for whatever imaginable reason) to change suffix, breaks all backwards compatibility
None of these problems would exist if...
- Two symbol names are not required for each system, or
- The user is required to specify both symbol names and thus maintains control over them
Both of which are possible solutions without negative side-effects to replace a design decision that comes with an otherwise growing grocery list of potential problems.
Guida per i contributori
Nessuna guida per i contributori indicizzata per questo repository
Valutazione
Questa issue non è ancora stata valutata.