Add example module to promote best practices

@quietone @smustgrave

The reason why I'm suggesting a core example module, instead of relying on the canonical examples project, is that, as a human, I tend to rely a lot on core modules themselves as examples. However, core modules are not always consistent in their implementation of best practices, it heavily depends on their "state of maintenance" within core and how often they change. This makes it hard to figure out which is the best source for inspiration. Moreover, in case of discrepancies, it's not clear which module "is right". My goal would be to ensure that all core modules follow a fixed pattern, at the least in their key parts, and that we have an official "source of truth" that can settle the debate of how a certain bit of logic should be implemented – and document the rationale.

I don't think the examples module is the right fit for this specific use case, because it's not readily available in the core codebase for anyone to look at. People may not even know it exists, whereas a core example linked from the README would be much more likely to be discovered.

Anyway, even if we end up not doing this, I'd still like to keep the issue around until we have a set of documented guidelines on how to author tests and how to make your code more unit testable – I'm going to open a separate issue for that shortly. For now the goal has been to be able to open a MR and post the examples I demoed during this session, so that we have some actual code to discuss.

Btw, would you mind expanding on why you think having an example module in core is not desirable?

@smustgrave

Thanks for the clarifications!

Here's the ticket to discuss the guidelines/best practices themselves: #3627934: Promote unit testability via code best practices.

@smustgrave:

And as mentioned helping AI, as I saw in the parent one of the tasks was to update AI best practices, downloading a contrib module seems like something it can do.

AI is not the key focus of the initiative, although agents will definitely benefit from a faster test suite and a better organized codebase. The AI-related item in the parent issue is to ensure that the AI best practices reflect the outcome of these discussions. At the moment, those practices recommend not using unit tests, whereas increasing their use is a cornerstone of the Test Pyramid proposal.

I initially loved the @best-practice suggestion, but on second thought, I think the same concern applies to it as to the example code: what if it becomes obsolete? You'd then be back to different parts of core disagreeing on what a best practice is—and, even worse, they'd both claim to be implementing a best practice. Super confusing.

OTOH, a core example module would be the central place for such an authoritative role: we could have a gate saying that you can't introduce new ways of doing things without updating the example/template code. Any disagreement would then be automatically resolved in favor of that.

I'm not a fan of the idea of a hidden example module lying around in core either, but honestly I cannot give a good reason why that's a bad idea, other than "I don't like it" :)
(and, of course, that we already have the examples project, which unfortunately is not in core ;)

I created an issue in the examples project queue referencing this. Hopefully we'll get some useful perspective :)