-
Notifications
You must be signed in to change notification settings - Fork 0
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Code Generation Post #7
base: master
Are you sure you want to change the base?
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
great article overall! had a few comments here and there
Computers writing code for other computers to run has a very Skynet feel to it | ||
and sounded too complicated to ever be worth the effort. | ||
Yet, this practice is so commonplace that there's [built-in | ||
support](https://docs.bazel.build/versions/main/be/general.html#genrule) for it |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
CSS nit: you should use the a:hover
selector so that the UX for links is better. I almost didn't think that this was a hyperlink.
Quick preface: I'm talking about writing a computer program that outputs | ||
some kind of file that's funny designed to be read in by a compiler or | ||
interpreter. I'm not talking about writing data files or schema files. It feels | ||
natural for computers to be writing those, since they broadly match up with the | ||
native data types found in programming languages. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the grammar here is a little confusing. suggested rewrite for clarity (you don't have to take the way i rewrote it, you can do a different way too):
Quick preface: I'm talking about writing a computer program that outputs | |
some kind of file that's funny designed to be read in by a compiler or | |
interpreter. I'm not talking about writing data files or schema files. It feels | |
natural for computers to be writing those, since they broadly match up with the | |
native data types found in programming languages. | |
Quick preface: I'm talking about writing a computer program that outputs | |
some kind of funny file that's designed to be read by a compiler or | |
interpreter (not a human). I'm not talking about writing data files or schema files, which | |
are pretty natural for computers to be writing, since they broadly match up with the | |
native data types found in programming languages. |
|
||
If you haven't seen GCP lately, there's an unbelievable amount of resource types | ||
(in the order of hundreds!). Everytime a user wishes to work with a resource of | ||
a certain type in one of those tools, there has to be code in that cool that |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
a certain type in one of those tools, there has to be code in that cool that | |
a certain type in one of those tools, there has to be code in that tool that |
resource types and have to make the same fix twelve times. Now, imagine doing | ||
it a hundred times. | ||
|
||
Code generation lets us create a source-of-truth for all this boilerplate. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Really well written section overall -- it almost feels like you're telling a story, the way you're narratively walking the reader through the motivation here.
|
||
The approach we take is essentially Mad Libs. | ||
|
||
<img src="/codegen.png" class="img-fluid hero-image" alt="Codegen example"> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nit: alt text here could be more descriptive for accessibility purposes.
|
||
## Templated Approach | ||
|
||
The approach we take is essentially Mad Libs. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
idea: I think it may be useful to start this section off by talking about templating being used with strings in languages, like C# string interpolation or C++ std::format
, as these are things many people may have experience with. you could then motivate that you're applying the same principals but at the scale of entire files and more.
function that replicates that template at runtime, and then replace the | ||
template with a single line of template code. We can more easily test our | ||
handwritten function. At that point, we just have to make sure that the | ||
template places the correct values into the function. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Love this section. I think it doesn't feel like a conclusion though, it feels like it abruptly ends here. Might suggest writing some sort of conclusion or something!
discover more places where customizations need to occur, those customizations | ||
become embedded into our templates. IDEs have poor support for understanding | ||
template syntax, leaving it up to the team to carefully parse our templates and | ||
understand what's happening. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
glad you discuss the cons to this approach too!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Mostly some quick nitpicks, but I haven't included thoughts on the overall structure or anything. The main thing I noticed was that the post ends rather abruptly.
in Google's build system. | ||
|
||
Quick preface: I'm talking about writing a computer program that outputs | ||
some kind of file that's funny designed to be read in by a compiler or |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
some kind of file that's funny designed to be read in by a compiler or | |
some kind of file that's designed to be read in by a compiler or |
similar. They all follow the same rough logic: | ||
|
||
- A user needs a cloud resource to exist in a certain manner | ||
- The tool calls that cloud resource's GET API to see if the resource exists. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
GET/Create/update all have different capitalization, better to be consistent
|
||
## How to Generate Code | ||
|
||
There's several different approaches to code generation. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There's several different approaches to code generation. | |
There are several different approaches to code generation. |
with some amount of this. That's not actually the method I'm going to be | ||
talking about. While you don't have to have a compiler background to do this, | ||
it does require knowledge of your language's internals. Testing will be more | ||
straightforward of any of these. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't understand the last sentence.
infrastructure to create Markdown documentation, Go code, Python code, | ||
protobufs, YAML files and anything in between. | ||
|
||
The downside to this approach is that the templates can grow unwiedy. As we |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The downside to this approach is that the templates can grow unwiedy. As we | |
The downside to this approach is that the templates can grow unwieldy. As we |
the hunt for more edge cases in generated code, so we can improve the generator | ||
better. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
the hunt for more edge cases in generated code, so we can improve the generator | |
better. | |
the hunt for more edge cases in generated code, so we can improve the generator. |
I suspect that this is why using "compiler magic" is so much more tenable for | ||
teams. It's easier to write unit tests when you have handfuls of functions that | ||
all alter an AST. That's how developers learn to write code! Write a function | ||
and then write a text for that function. A template approach means that most of |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
and then write a text for that function. A template approach means that most of | |
and then write a test for that function. A template approach means that most of |
Our team does rewrites where we take a large amount of template, write a | ||
function that replicates that template at runtime, and then replace the | ||
template with a single line of template code. We can more easily test our |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This sentence is kinda "yo dawg, I heard you like templates". Consider restructuring, especially to distinguish the different uses of "template".
Our team does rewrites where we take a large amount of template, write a | ||
function that replicates that template at runtime, and then replace the | ||
template with a single line of template code. We can more easily test our | ||
handwritten function. At that point, we just have to make sure that the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
handwritten function. At that point, we just have to make sure that the | |
handwritten function than the original template. At that point, we just have to make sure that the |
function that replicates that template at runtime, and then replace the | ||
template with a single line of template code. We can more easily test our | ||
handwritten function. At that point, we just have to make sure that the | ||
template places the correct values into the function. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"template" here is also a little confusing because of the overuse above.
Adding a post to talk about code generation