[pigeon] Creates writePrologue method on Generator classes

[tarrinneal]

Adds writePrologue method to Generator classes and updates tests to use new Generators.

work towards flutter/flutter#117416

Waiting for #2996 to merge

[gaaclarke]

If I'm understanding this correctly, the only client of writeFileHeaders is the implementations of generate, right? In that sense writeFileHeaders is not really an abstraction over Generator implementations that has any meaning. Generator implementations can just ignore that method. I don't see value in this change beyond the value of just splitting out the logic into it's own procedure, which I think we already had everywhere.

Now we could force it to have meaning by having pigeon_lib call into it. I don't know if that actually makes the code any clearer though.

I haven't had a chance to look at the other PRs you have for this cleanup but I think if there is more, it's worth creating a design doc that we can iterate on more quickly. I can help you with that if you want by drawing up where we are at now, then all you have to do is tweak the changes we are thinking of making.

[gaaclarke]

I talked to Tarrin offline and we decided to circle back to his design doc on this refactor. After talking about it, this refactor sounds like a good approach generally but I'd like to:

1. Make sure we agree on a final state (including naming and stuff)
2. Incrementally build on the extraction of logic from the Generators with each PR

[stuartmorgan-g]

Why do we need to fully design and name every element of the final state in advance? The problem we have right now is that the generators are big soups of methods with no parallel structure (thus hard to maintain, and with no ability to leverage parallel structure).

The goal is to have a central structure of common elements. That lends itself extremely well to incremental, bottom-up extraction of clearly parallel parts (e.g., every generator needs to output each data class, so a method to write the data class is an obvious common element to extract; do that then rinse and repeat). A key advantage of that approach is that each step is simple and clear, and over time makes it much easier to see what high-level driving logic is fully the same, and which isn't, which will inform the final state.

It's much harder to see the right final states when we mostly have soup, so I'm not sure why we want to do all the design work at the point where it's hardest. What are the specific concerns with incremental extraction?

[gaaclarke]

I don't want to turn code reviews into design reviews. The goal of what we are trying to accomplish is make the codebase have more form and less duplication. To be clear, I think we are on the right path generally.

The last PR I had to give some design feedback and that creates undue work on the contributor since they have to update code, if we are able to have those discussions before the code was written the process will go more smoothly and the results will be better. We have enough information about what the code is doing and what we want to accomplish we should be able to convey our design.

I've written up a design based on what Tarrin and I have discussed in PlantUML and gave him the source code so he can tweak it. I think that will be a good jumping off point for us all to get on the same page.

[gaaclarke]

The goal is to have a central structure of common elements.

Here's one specific open design question, where does that shared structure should live:

1. Docstrings and abstract (essentially private) methods in Generator? (current path)
2. Pigeon.run()'s logic and the public interface for Generator?
3. In an abstract base class which structured Generators inherit from? (the proposal I just made to Tarrin)