Demystifying Code Generation: Building Programs That Build Programs
July 17, 2023

Keith Casey
ngrok

Code generation is the art of writing programs that write other programs. The most common place to use code generation is for generating libraries. In those scenarios, you have a fixed specification in a domain-specific language (DSL) and a code generator uses that to create the function or API calls representing individual requests or pieces of functionality. While code generation seems simple at first, there are many sharp corners and hidden surprises in anything beyond the most trivial scenarios.

But before you decide whether to build a code generator or not, exploring the depths, complexity, and tradeoffs is key. Sometimes, this exploration will lead you to realize your time is better spent extending common tools to meet your unique use case. But there are many scenarios where creating a custom code generator is your best option. Before you explore, let’s consider one concrete scenario were you’d want a code generator and the best practices to make it useful in the long term.

When to Write a Custom Code Generator

Imagine creating a web service that requires email address validation. To ensure the email addresses are valid, the "correct" validation regular expression is wildly complex and obtuse. That said, there are a handful of easier aspects to check — like too many characters or missing an "@" — so we can start there. Initially, you rely on standard library methods like fmt.Errorf to report errors but will find that it doesn’t give the user enough information about the error. To counter that, you add two unique error codes, "email too long" and "invalid email," to make it easier for the user to understand why their email address won’t validate.

You could embed the unique error codes as ad hoc strings within existing strings, but this lacks structure and depends on downstream developers or the user to understand your new pseudo-convention. Alternatively, you could create a function that takes a unique error code as a parameter but that still relies on strings and will lead to inconsistent implementations. So how can you uplevel the implementation?

One solution is to generate unique functions for each error you want to handle. This allows for specialized error types, facilitating observability and enabling higher-level code components to work with specific error conditions. However, manually defining all these functions is time-consuming, especially for programs with hundreds or thousands of errors.

This is where writing a custom code generator comes in handy. By defining errors in a reusable format like a YAML file, you can generate the necessary functions. This approach simplifies error management, promotes consistency, reuses these checks across projects and enables the generation of functions for multiple programming languages. You can create a unified error repository for the software, ensuring clear communication and streamlined error handling.

Code Generation Best Practices

When writing a custom code generator, you should first consider the scope and complexity of creating it. There are always trade-offs between customization and simplicity, and developers should aim to understand these up front before diving in. Once you decide to write a custom code generator, developers must keep these best practices in mind.

1. Use comments to prevent edits: You should use comments to give other developers instructions on how to use and edit the code. Comments can tell other teammates not to modify the generated code directly and point them to the source of truth where they should make changes.

2. Isolate generated files: Developers should separate generated files from human-written code by using distinct suffixes or separate directories. Isolation enhances developer experience and makes it easier to identify machine-generated files, simplifying tasks like file filtering or removing outdated generated files.

3. Use a consistent template structure: A consistent template file is crucial for writing an effective code generator because it promotes a standardized format, reduces duplication, and allows for easy modification and maintenance. It facilitates collaboration among developers and enables extensibility for future enhancements.

How to Leverage Code Generation

If you’re considering code generation, start small. Write custom tooling that you never plan on releasing to the world. Explore, play, break things, figure out strengths and weaknesses and find the bounds of what’s possible. That way, when you inevitably consider code generation in practice, you’ll better understand the effort it takes to write and maintain a custom code generator or tailor something that already exists.

With the right tools and practices, code generation is an accessible and valuable tool in your toolbox. It offers a straightforward approach to automating repetitive tasks and establishing conventions. It’s one of the many ways you can solve complex problems, and it just might help you do it in fewer lines of code.

Keith Casey is Director of Product Marketing at ngrok
Share this

Industry News

January 30, 2025

OutSystems announced the general availability (GA) of Mentor on OutSystems Developer Cloud (ODC).

January 30, 2025

Kurrent announced availability of public internet access on its managed service, Kurrent Cloud, streamlining the connectivity process and empowering developers with ease of use.

January 29, 2025

MacStadium highlighted its major enterprise partnerships and technical innovations over the past year. This momentum underscores MacStadium’s commitment to innovation, customer success and leadership in the Apple enterprise ecosystem as the company prepares for continued expansion in the coming months.

January 29, 2025

Traefik Labs announced the integration of its Traefik Proxy with the Nutanix Kubernetes Platform® (NKP) solution.

January 28, 2025

Perforce Software announced the launch of AI Validation, a new capability within its Perfecto continuous testing platform for web and mobile applications.

January 28, 2025

Mirantis announced the launch of Rockoon, an open-source project that simplifies OpenStack management on Kubernetes.

January 28, 2025

Endor Labs announced a new feature, AI Model Discovery, enabling organizations to discover the AI models already in use across their applications, and to set and enforce security policies over which models are permitted.

January 27, 2025

Qt Group is launching Qt AI Assistant, an experimental tool for streamlining cross-platform user interface (UI) development.

January 27, 2025

Sonatype announced its integration with Buy with AWS, a new feature now available through AWS Marketplace.

January 27, 2025

Endor Labs, Aikido Security, Arnica, Amplify, Kodem, Legit, Mobb and Orca Security have launched Opengrep to ensure static code analysis remains truly open, accessible and innovative for everyone:

January 23, 2025

Progress announced the launch of Progress Data Cloud, a managed Data Platform as a Service designed to simplify enterprise data and artificial intelligence (AI) operations in the cloud.

January 23, 2025

Sonar announced the release of its latest Long-Term Active (LTA) version, SonarQube Server 2025 Release 1 (2025.1).

January 23, 2025

Idera announced the launch of Sembi, a multi-brand entity created to unify its premier software quality and security solutions under a single umbrella.

January 22, 2025

Postman announced the Postman AI Agent Builder, a suite empowering developers to quickly design, test, and deploy intelligent agents by combining LLMs, APIs, and workflows into a unified solution.

January 22, 2025

The Cloud Native Computing Foundation® (CNCF®), which builds sustainable ecosystems for cloud native software, announced the graduation of CubeFS.