owlkettle icon indicating copy to clipboard operation
owlkettle copied to clipboard

Add State Refs

Open PhilippMDoerner opened this issue 2 weeks ago • 19 comments

This PR is a draft to demonstrate how I plan on acting while in the DSL part of the code.

Given that macros and DSLs in general have a tendency to be pretty mean in terms of complexity, I developed a few habits over the years to structure those well enough so I can more easily get back into it after a while.

I plan on introducing some of those in the owlkettle DSL because I believe them to be beneficial to the overall project and for readability.

I wanted to open up this PR to already show you how I tend to act on every proc I touch when it comes to these to give you the chance to veto any of these habits up front. (Sidenote, the below proc I mostly touched because I originally added a stateRef field to the generated WidgetState, then realized that's unnecessary, but at that point I'd already written myself a doc comment and it felt like a waste to throw that away)

In general:

  • Add doc comments to any proc involved in code generation. Even private procs. Procs that generate NimNodes and thus Code directly I also annotate with a pattern that demonstrates what they generate (see doc comment in the code)
  • A variable should always only hold one type of NimNodeKind. I just found it a ton easier to reason about what a given NimNode is if I can know for sure what NimNodeKind it is. That's visible here in how I replaced the bits of result with var fieldName until the final code generation step
  • Separate sections in a proc into either smaller procs with fitting names, or at the very least split with doc comments. Code-generating related procs tend to become hard to see what they're about really fast, which is why I have this rule so you have something that allows you to see at a glance what this codeblock is about.

PhilippMDoerner avatar Jun 17 '24 18:06 PhilippMDoerner